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

package/scripts/lib/brand.js

@@ -0,0 +1,41 @@
+/* global hexo */
+"use strict";
+
+function normalizeBrand(brand) {
+  const result = {};
+  for (const key of ["name", "tagline", "href"]) {
+    if (brand?.[key] !== undefined) result[key] = brand[key];
+  }
+  if (brand?.image && typeof brand.image === "object") {
+    const image = {};
+    for (const key of ["src", "variant"]) {
+      if (brand.image[key] !== undefined) image[key] = brand.image[key];
+    }
+    if (Object.keys(image).length > 0) result.image = image;
+  }
+  return result;
+}
+
+function shouldShowMobileBrand({ profileKey }) {
+  return [
+    "home",
+    "blogIndex",
+    "wikiIndex",
+    "notebooks",
+    "notebook"
+  ].includes(profileKey);
+}
+
+function replaceConfigTokens(value, config) {
+  if (typeof value !== "string") return "";
+  return value
+    .replaceAll("{config.title}", config?.title || "")
+    .replaceAll("{config.subtitle}", config?.subtitle || "")
+    .replaceAll("{config.avatar}", config?.avatar || "");
+}
+
+module.exports = {
+  normalizeBrand,
+  replaceConfigTokens,
+  shouldShowMobileBrand
+};

package/scripts/lib/browser-runtime.js

@@ -0,0 +1,115 @@
+/* global hexo */
+
+"use strict";
+
+const INTERNAL_CONSTANTS = require("./internal-constants");
+const { buildContributionEntries } = require("./contribution-registry");
+const { resolveServiceProvider } = require("./service-provider");
+
+const RUNTIME_VERSION = 1;
+const RUNTIME_CONFIG_ID = "stellar-runtime-config";
+const LOCAL_MODULE_PREFIX = "/js/runtime/";
+
+function deepFreeze(value) {
+  if (value == null || typeof value !== "object" || Object.isFrozen(value)) return value;
+  Object.values(value).forEach(deepFreeze);
+  return Object.freeze(value);
+}
+
+function plainObject(value, path) {
+  if (value == null) return {};
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`[stellar runtime] ${path} must be an object`);
+  }
+  return value;
+}
+
+function validateWhen(value, path) {
+  const when = plainObject(value, path);
+  const keys = Object.keys(when);
+  if (keys.length !== 1 || !["always", "selector"].includes(keys[0])) {
+    throw new TypeError(`[stellar runtime] ${path} must declare exactly one of always/selector`);
+  }
+  if (keys[0] === "always" && when.always !== true) {
+    throw new TypeError(`[stellar runtime] ${path}.always must be true`);
+  }
+  if (keys[0] === "selector" && (typeof when.selector !== "string" || when.selector.length === 0)) {
+    throw new TypeError(`[stellar runtime] ${path}.selector must be a non-empty string`);
+  }
+  return when;
+}
+
+function validateEntry(entry, index, ids) {
+  plainObject(entry, `extensions[${index}]`);
+  const allowed = new Set(["id", "module", "when", "config"]);
+  const unknown = Object.keys(entry).filter(key => !allowed.has(key));
+  if (unknown.length > 0) {
+    throw new TypeError(`[stellar runtime] extensions[${index}] has unknown field ${unknown[0]}`);
+  }
+  if (typeof entry.id !== "string" || !/^[a-z][a-z0-9-]*$/.test(entry.id)) {
+    throw new TypeError(`[stellar runtime] extensions[${index}].id is invalid`);
+  }
+  if (ids.has(entry.id)) {
+    throw new TypeError(`[stellar runtime] duplicate extension id ${entry.id}`);
+  }
+  ids.add(entry.id);
+  if (typeof entry.module !== "string" || !entry.module.startsWith(LOCAL_MODULE_PREFIX) || !entry.module.endsWith(".js")) {
+    throw new TypeError(`[stellar runtime] extensions[${index}].module must be a local runtime .js path`);
+  }
+  validateWhen(entry.when, `extensions[${index}].when`);
+  plainObject(entry.config, `extensions[${index}].config`);
+}
+
+function normalizeRoot(value) {
+  const root = typeof value === "string" && value.length > 0 ? value : "/";
+  return root.endsWith("/") ? root : `${root}/`;
+}
+
+function buildBrowserRuntimeManifest(input) {
+  const source = plainObject(input, "input");
+  const extensions = plainObject(source.extensions, "extensions");
+  const features = plainObject(extensions.features, "extensions.features");
+  const assets = plainObject(source.assets, "assets");
+  const render = plainObject(source.render, "render");
+  const messages = plainObject(source.messages, "messages");
+  const root = normalizeRoot(source.root);
+  const comments = plainObject(source.comments, "comments");
+  const entries = buildContributionEntries({
+    assets,
+    colorScheme: source.colorScheme,
+    comments,
+    extensions,
+    features,
+    messages,
+    plainObject,
+    render,
+    resolveServiceProvider
+  });
+
+  const manifest = {
+    version: RUNTIME_VERSION,
+    root,
+    policy: Object.assign({}, INTERNAL_CONSTANTS.runtime, { providers: INTERNAL_CONSTANTS.providers }),
+    dependencies: assets.dependencies || {},
+    extensions: entries
+  };
+  const ids = new Set();
+  entries.forEach((entry, index) => validateEntry(entry, index, ids));
+  return deepFreeze(manifest);
+}
+
+function serializeBrowserRuntimeManifest(manifest) {
+  return JSON.stringify(manifest)
+    .replace(/&/g, "\\u0026")
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+module.exports = {
+  RUNTIME_CONFIG_ID,
+  RUNTIME_VERSION,
+  buildBrowserRuntimeManifest,
+  serializeBrowserRuntimeManifest
+};

package/scripts/lib/caption.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const { stripHTML } = require('hexo-util');
+
+// 卡片与置顶区的一行说明：显式 tagline > description > excerpt/content。
+function caption(item, length = 50) {
+  if (item == null) return '';
+  const tagline = item.tagline;
+  if (tagline != null && String(tagline).length > 0) {
+    const separator = String(tagline).indexOf(' | ');
+    return separator > 0 ? String(tagline).slice(0, separator) : tagline;
+  }
+  if (item.description != null && String(item.description).length > 0) {
+    return item.description;
+  }
+  const text = stripHTML(item.excerpt || item.content || '').replace(/\s+/g, ' ').trim();
+  if (text.length === 0) return '';
+  return text.length > length ? text.slice(0, length) : text;
+}
+
+module.exports = { caption };

package/scripts/lib/collection-pipeline/adapters/notebook.js

@@ -0,0 +1,62 @@
+"use strict";
+
+const {
+  buildNotebookCollectionModel,
+  buildNotebookPageViewModelBase
+} = require("../../models");
+const {
+  setProfileViewModelBase,
+  setProfileViewModelInput
+} = require("../../page-view-model-registry");
+const { sourcePathForData } = require("../../source-config");
+const { plainTerms } = require("../shared");
+
+module.exports = {
+  id: "notebook",
+  config: Object.freeze({
+    collection: Object.freeze({
+      hero: false,
+      routeStart: false,
+      navigationTree: false,
+      listing: Object.freeze(["order", "excerptLength", "perPage", "sort"])
+    }),
+    page: Object.freeze({ listingPriority: true })
+  }),
+  contentKind: "pages",
+  twoStage: true,
+  prepare(pipeline) {
+    const collectionItems = pipeline.members("notebook").map(record => ({
+      collection: { profile: "notebook", id: record.collectionId },
+      tags: plainTerms(record.config.tags)
+    }));
+    const collectionModels = new Map();
+    for (const [collectionId, collectionConfig] of pipeline.collections("notebook")) {
+      collectionModels.set(collectionId, buildNotebookCollectionModel({
+        collectionSource: sourcePathForData(`notebooks/${collectionId}`),
+        themeSource: pipeline.themeSource,
+        siteConfig: pipeline.ctx.config,
+        stellarConfig: pipeline.ctx.stellar?.config,
+        collectionConfig,
+        collectionItems
+      }, collectionId));
+    }
+    for (const record of pipeline.members("notebook")) {
+      pipeline.capture(() => {
+        const collectionId = record.collectionId;
+        const input = pipeline.modelInput(record, {
+          collectionSource: sourcePathForData(`notebooks/${collectionId}`),
+          collectionId,
+          collectionConfig: pipeline.collection("notebook", collectionId),
+          collectionModel: collectionModels.get(collectionId),
+          collectionItems
+        });
+        const base = buildNotebookPageViewModelBase(input);
+        setProfileViewModelInput("notebook", record.page, input);
+        setProfileViewModelBase("notebook", record.page, base);
+      });
+    }
+  },
+  build(pipeline) {
+    require("../../../events/lib/notebooks")(pipeline.ctx, pipeline);
+  }
+};

package/scripts/lib/collection-pipeline/adapters/post.js

@@ -0,0 +1,20 @@
+"use strict";
+
+const { setProfileViewModelInput } = require("../../page-view-model-registry");
+
+module.exports = {
+  id: "post",
+  config: Object.freeze({
+    collection: null,
+    page: Object.freeze({ listingPriority: true })
+  }),
+  contentKind: "posts",
+  twoStage: false,
+  prepare(pipeline) {
+    for (const record of pipeline.members("post")) {
+      setProfileViewModelInput("post", record.page, pipeline.modelInput(record, {
+        isBackup: process.env.IS_BACKUP === "true"
+      }));
+    }
+  }
+};

package/scripts/lib/collection-pipeline/adapters/topic.js

@@ -0,0 +1,82 @@
+"use strict";
+
+const {
+  buildTopicIndexRender,
+  buildTopicPageViewModelBase,
+  completeTopicPageViewModel
+} = require("../../models");
+const {
+  setProfileViewModelBase,
+  setProfileViewModelInput
+} = require("../../page-view-model-registry");
+const { sourcePathForData } = require("../../source-config");
+const { runTwoStage } = require("../shared");
+
+module.exports = {
+  id: "topic",
+  config: Object.freeze({
+    collection: Object.freeze({
+      hero: false,
+      routeStart: true,
+      navigationTree: false,
+      listing: Object.freeze(["excerptLength", "sort"])
+    }),
+    page: Object.freeze({ listingPriority: true })
+  }),
+  contentKind: "posts",
+  twoStage: true,
+  prepare(pipeline) {
+    const members = pipeline.members("topic");
+    const memberSnapshots = Object.freeze(members.map(record => Object.freeze({
+      source: pipeline.sourceForPage(record.page),
+      frontMatter: record.config,
+      page: record.snapshot
+    })));
+    const publishList = Array.isArray(pipeline.data.topic?.publish_list)
+      ? pipeline.data.topic.publish_list
+      : null;
+    const topicIndexItems = [];
+    for (const [collectionId, collectionConfig] of pipeline.collections("topic")) {
+      pipeline.capture(() => topicIndexItems.push(buildTopicIndexRender({
+        source: sourcePathForData(`topic/${collectionId}`),
+        themeSource: pipeline.themeSource,
+        collectionSource: sourcePathForData(`topic/${collectionId}`),
+        collectionId,
+        collectionListed: publishList == null || publishList.includes(collectionId),
+        siteConfig: pipeline.ctx.config,
+        runtimeData: pipeline.runtimeData,
+        stellarConfig: pipeline.ctx.stellar?.config,
+        collectionConfig,
+        members: memberSnapshots
+      })));
+    }
+    pipeline.runtimeData.topicIndex = Object.freeze({ items: Object.freeze(topicIndexItems) });
+
+    runTwoStage(members, {
+      buildBase(record) {
+        return pipeline.capture(() => {
+          const collectionId = record.collectionId;
+          const input = pipeline.modelInput(record, {
+            collectionSource: sourcePathForData(`topic/${collectionId}`),
+            collectionId,
+            collectionListed: publishList == null || publishList.includes(collectionId),
+            collectionConfig: pipeline.collection("topic", collectionId),
+            members: memberSnapshots
+          });
+          const base = buildTopicPageViewModelBase(input);
+          setProfileViewModelInput("topic", record.page, input);
+          setProfileViewModelBase("topic", record.page, base);
+          return { input, base };
+        });
+      },
+      aggregate() {
+        return pipeline.runtimeData.topicIndex;
+      },
+      complete(record, prepared) {
+        if (!prepared) return null;
+        record.page.viewModel = completeTopicPageViewModel(prepared.input, prepared.base);
+        return record.page.viewModel;
+      }
+    });
+  }
+};

package/scripts/lib/collection-pipeline/adapters/wiki.js

@@ -0,0 +1,20 @@
+"use strict";
+
+module.exports = {
+  id: "wiki",
+  config: Object.freeze({
+    collection: Object.freeze({
+      hero: true,
+      routeStart: false,
+      navigationTree: true,
+      listing: Object.freeze(["priority", "order"])
+    }),
+    page: Object.freeze({ listingPriority: false })
+  }),
+  contentKind: "pages",
+  twoStage: true,
+  prepare() {},
+  build(pipeline) {
+    require("../../../events/lib/doc_tree")(pipeline.ctx, pipeline);
+  }
+};

package/scripts/lib/collection-pipeline/index.js

@@ -0,0 +1,169 @@
+"use strict";
+
+const {
+  ContentConfigError,
+  parseCollectionConfig,
+  parsePageConfig,
+  validateCollectionProfileConfig,
+  validatePageProfileConfig,
+  validateThemeConfig
+} = require("../../lib/content-config");
+const { formatConfigWarnings } = require("../../lib/config-schema");
+const { resetPageViewModelRegistry, setPageConfig } = require("../page-view-model-registry");
+const { ensureRuntimeData } = require("../runtime-data");
+const { readFrontMatter, sourcePathForData, sourcePathForPage } = require("../source-config");
+const {
+  createCollectionRegistry,
+  resolveContentMembership
+} = require("../content-membership");
+const { discoverContent, memberKey } = require("./shared");
+const { getProfileAdapter, profileAdapters } = require("./registry");
+
+function prepareCollectionPipeline(ctx) {
+  resetPageViewModelRegistry();
+  const issues = [];
+  const configWarnings = [];
+  const data = ctx.locals.get("data") || {};
+  const collectionConfigs = new Map();
+  const pageConfigs = new Map();
+  ctx.stellar ||= {};
+  const themeConfig = ctx.config.theme_config ?? ctx.theme.config;
+  const themeSource = ctx.config.theme_config !== undefined
+    ? "_config.stellar.yml"
+    : "themes/stellar/_config.yml";
+  const runtimeData = ensureRuntimeData(ctx);
+
+  const capture = operation => {
+    try {
+      return operation();
+    } catch (error) {
+      if (!(error instanceof ContentConfigError)) throw error;
+      issues.push(...error.issues);
+      return null;
+    }
+  };
+
+  capture(() => validateThemeConfig(themeConfig, themeSource));
+  for (const [key, value] of Object.entries(data)) {
+    if (!key.startsWith("wiki/") && !key.startsWith("topic/") && !key.startsWith("notebooks/")) continue;
+    capture(() => {
+      const profile = key.startsWith("notebooks/") ? "notebook" : key.split("/", 1)[0];
+      const source = sourcePathForData(key);
+      const parsed = parseCollectionConfig(value, source, {
+        mode: "recover",
+        onIssues: current => configWarnings.push(...current)
+      });
+      validateCollectionProfileConfig(parsed, source, profile, getProfileAdapter(profile).config);
+      collectionConfigs.set(key, parsed);
+    });
+  }
+  const membershipRegistry = createCollectionRegistry(collectionConfigs);
+
+  const configForPage = (page, kind) => {
+    if (pageConfigs.has(page)) return pageConfigs.get(page);
+    const raw = readFrontMatter(ctx, page);
+    if (raw == null) {
+      pageConfigs.set(page, null);
+      return null;
+    }
+    let parsed = capture(() => parsePageConfig(raw, sourcePathForPage(page), {
+      mode: "recover",
+      onIssues: current => configWarnings.push(...current)
+    }));
+    if (parsed != null) {
+      const resolved = resolveContentMembership({
+        kind,
+        source: sourcePathForPage(page),
+        pagePath: page.path,
+        config: parsed,
+        registry: membershipRegistry
+      });
+      if (resolved.issues.length > 0) {
+        issues.push(...resolved.issues);
+        parsed = null;
+      } else {
+        parsed = resolved.config;
+        const profile = parsed.collection?.profile || (kind === "posts" ? "post" : "page");
+        const adapter = profile === "page" ? null : getProfileAdapter(profile);
+        validatePageProfileConfig(parsed, sourcePathForPage(page), profile, adapter?.config);
+      }
+    }
+    pageConfigs.set(page, parsed);
+    if (parsed != null) {
+      setPageConfig(page, parsed);
+    }
+    return parsed;
+  };
+
+  const discovery = discoverContent({
+    posts: ctx.locals.get("posts"),
+    pages: ctx.locals.get("pages"),
+    configForPage
+  });
+  const collectionMap = new Map();
+  for (const [key, config] of collectionConfigs) {
+    const matched = key.match(/^(wiki|topic|notebooks)\/(.+)$/);
+    if (!matched) continue;
+    const profile = matched[1] === "notebooks" ? "notebook" : matched[1];
+    collectionMap.set(memberKey(profile, matched[2]), config);
+  }
+
+  const pipeline = {
+    ctx,
+    data,
+    runtimeData,
+    themeSource,
+    discovery,
+    capture,
+    sourceForPage: sourcePathForPage,
+    members(profile, collectionId) {
+      return collectionId == null
+        ? discovery.byProfile.get(profile) || Object.freeze([])
+        : discovery.byCollection.get(memberKey(profile, collectionId)) || Object.freeze([]);
+    },
+    collection(profile, id) {
+      return collectionMap.get(memberKey(profile, id));
+    },
+    collections(profile) {
+      const result = [];
+      for (const [key, value] of collectionMap) {
+        if (key.startsWith(`${profile}:`)) result.push([key.slice(profile.length + 1), value]);
+      }
+      return result;
+    },
+    modelInput(record, extra = {}) {
+      return Object.freeze({
+        source: sourcePathForPage(record.page),
+        themeSource,
+        siteConfig: ctx.config,
+        runtimeData,
+        stellarConfig: ctx.stellar?.config,
+        frontMatter: record.config,
+        page: record.snapshot,
+        ...extra
+      });
+    }
+  };
+
+  const adapters = profileAdapters();
+  for (const adapter of adapters) adapter.prepare?.(pipeline);
+
+  const warning = formatConfigWarnings(configWarnings);
+  if (warning) ctx.log.warn(warning);
+  if (issues.length > 0) throw new ContentConfigError(issues);
+  pipeline.summary = Object.freeze({
+    profiles: Object.freeze(adapters.map(adapter => adapter.id)),
+    contentVisits: discovery.visits,
+    members: discovery.records.length
+  });
+  return pipeline;
+}
+
+function runCollectionPipeline(ctx) {
+  const pipeline = prepareCollectionPipeline(ctx);
+  for (const adapter of profileAdapters()) adapter.build?.(pipeline);
+  pipeline.runtimeData.collectionPipeline = pipeline.summary;
+  return pipeline;
+}
+
+module.exports = { prepareCollectionPipeline, runCollectionPipeline };

package/scripts/lib/collection-pipeline/registry.js

@@ -0,0 +1,27 @@
+"use strict";
+
+const adapters = [
+  require("./adapters/post"),
+  require("./adapters/topic"),
+  require("./adapters/wiki"),
+  require("./adapters/notebook")
+];
+
+const PROFILE_IDS = Object.freeze(adapters.map(adapter => adapter.id));
+const registry = new Map(adapters.map(adapter => [adapter.id, Object.freeze(adapter)]));
+
+function getProfileAdapter(id) {
+  const adapter = registry.get(id);
+  if (!adapter) throw new Error(`Stellar v2: 未登记的 Collection profile ${id}`);
+  return adapter;
+}
+
+function profileAdapters() {
+  return PROFILE_IDS.map(getProfileAdapter);
+}
+
+module.exports = {
+  PROFILE_IDS,
+  getProfileAdapter,
+  profileAdapters
+};