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

package/scripts/schema/config-rules.js

@@ -0,0 +1,290 @@
+"use strict";
+
+const { SHARE_SERVICE_IDS } = require("../lib/share-services");
+
+function literal(value) {
+  return { kind: "literal", value };
+}
+
+function item(type, options = {}) {
+  return { type: Array.isArray(type) ? type : [type], default: literal(options.defaultValue), normalizer: options.normalizer || "identity", ...options };
+}
+
+const menuItem = item("object", {
+  defaultValue: {},
+  normalizer: "menu_item",
+  sealed: true,
+  properties: {
+    type: item("string", { defaultValue: "link", values: ["link", "search"] }),
+    id: item(["string", "null"], { defaultValue: null, validator: "nullable_kebab_id" }),
+    title: item(["string", "null"], { defaultValue: null }),
+    icon: item(["string", "null"], { defaultValue: null, validator: "nullable_non_empty_string" }),
+    url: item(["string", "null"], { defaultValue: null, validator: "nullable_safe_navigation_url" }),
+    accent: item(["string", "null"], { defaultValue: null, validator: "nullable_css_color" })
+  }
+});
+
+const footerActionItem = item("object", {
+  defaultValue: {},
+  normalizer: "footer_action_item",
+  sealed: true,
+  properties: {
+    type: item("string", { defaultValue: "link", values: ["link", "button"] }),
+    icon: item(["string", "null"], { defaultValue: null, validator: "nullable_non_empty_string" }),
+    title: item("string", { defaultValue: "", validator: "non_empty_string" }),
+    url: item(["string", "null"], { defaultValue: null, validator: "nullable_safe_navigation_url" }),
+    onclick: item(["string", "null"], { defaultValue: null, validator: "nullable_non_empty_string" })
+  }
+});
+
+const footerAction = item("object", {
+  defaultValue: {},
+  normalizer: "footer_action",
+  sealed: true,
+  properties: {
+    type: item("string", { defaultValue: "link", values: ["link", "button", "dropdown", "spacer"] }),
+    icon: item(["string", "null"], { defaultValue: null, validator: "nullable_non_empty_string" }),
+    title: item(["string", "null"], { defaultValue: null }),
+    url: item(["string", "null"], { defaultValue: null, validator: "nullable_safe_navigation_url" }),
+    onclick: item(["string", "null"], { defaultValue: null, validator: "nullable_non_empty_string" }),
+    items: item("array", { defaultValue: [], normalizer: "array", items: footerActionItem })
+  }
+});
+
+const aboutItem = item("object", {
+  defaultValue: {},
+  normalizer: "object",
+  sealed: true,
+  requiredProperties: ["key", "value"],
+  properties: {
+    key: item("string", { defaultValue: "", validator: "non_empty_string" }),
+    value: item("string", { defaultValue: "", validator: "non_empty_string" }),
+    url: item(["string", "null"], { defaultValue: null, validator: "nullable_template_navigation_url" })
+  }
+});
+
+const footerSectionItem = item("object", {
+  defaultValue: {},
+  normalizer: "object",
+  sealed: true,
+  requiredProperties: ["title", "url"],
+  properties: {
+    title: item("string", { defaultValue: "", validator: "non_empty_string" }),
+    url: item("string", { defaultValue: "", validator: "safe_navigation_url" })
+  }
+});
+
+const footerSection = item("object", {
+  defaultValue: {},
+  normalizer: "object",
+  sealed: true,
+  requiredProperties: ["title", "items"],
+  properties: {
+    title: item("string", { defaultValue: "", validator: "non_empty_string" }),
+    items: item("array", { defaultValue: [], normalizer: "array", items: footerSectionItem })
+  }
+});
+
+const navigationTab = item("object", {
+  defaultValue: {},
+  normalizer: "object",
+  sealed: true,
+  requiredProperties: ["title", "url"],
+  properties: {
+    title: item("string", { defaultValue: "", validator: "non_empty_string" }),
+    url: item("string", { defaultValue: "", validator: "safe_navigation_url" })
+  }
+});
+
+const contributorRepository = item("object", {
+  defaultValue: { branch: "main" },
+  normalizer: "object",
+  sealed: true,
+  requiredProperties: ["source_prefix", "repository"],
+  properties: {
+    source_prefix: item("string", { defaultValue: "", runtimeKey: "sourcePrefix", validator: "safe_relative_path" }),
+    repository: item("string", { defaultValue: "", validator: "github_repository" }),
+    branch: item("string", { defaultValue: "main", validator: "non_empty_string" })
+  }
+});
+
+const stringRecord = validator => ({
+  normalizer: "object",
+  sealed: false,
+  properties: {},
+  additionalPropertyKey: "<key>",
+  additionalProperties: item("string", { defaultValue: "", ...(validator ? { validator } : {}) })
+});
+
+const parameterBag = { normalizer: "parameter_bag", sealed: false };
+const widgetItems = item(["string", "object"], { defaultValue: null, normalizer: "parameter_bag", sealed: false });
+const brandImage = {
+  type: ["object"],
+  default: literal({ src: null, variant: "avatar" }),
+  normalizer: "object",
+  sealed: true,
+  properties: {
+    src: item(["string", "null"], { defaultValue: null, validator: "nullable_non_empty_string" }),
+    variant: item("string", { defaultValue: "avatar", values: ["avatar", "icon", "plain"] })
+  }
+};
+const brandProperties = {
+  image: brandImage,
+  name: item(["string", "null"], { defaultValue: null }),
+  tagline: item(["string", "null"], { defaultValue: null }),
+  href: item(["string", "null"], { defaultValue: "/", validator: "nullable_safe_navigation_url" })
+};
+const leftbarBrandProperties = {
+  style: item("string", { defaultValue: "regular", values: ["regular", "compact"] }),
+  ...brandProperties
+};
+const regionBrand = properties => ({
+  type: ["object", "boolean"],
+  normalizer: "parameter_bag",
+  sealed: true,
+  validator: "brand",
+  properties
+});
+const inheritedRegionBrand = properties => ({
+  ...regionBrand(properties),
+  type: ["object", "boolean", "null"],
+  defaultValue: null
+});
+
+const CONFIG_RULES = Object.freeze([
+  ["footer.sections", { items: footerSection }],
+  ["footer.content", { normalizer: "trusted_text" }],
+
+  ["topbar.enabled", { type: ["boolean"] }],
+  ["topbar.brand", regionBrand(brandProperties)],
+  ["topbar.menu", { validator: "menu_items", items: menuItem }],
+  ["topbar.widgets", { items: widgetItems }],
+  ["leftbar.default_state", { values: ["expanded", "collapsed"] }],
+  ["leftbar.enabled", { type: ["boolean"] }],
+  ["leftbar.brand", regionBrand(leftbarBrandProperties)],
+  ["leftbar.menu", { validator: "menu_items", items: menuItem }],
+  ["leftbar.footer.actions", { validator: "footer_actions", items: footerAction }],
+  ["leftbar.widgets", { items: widgetItems }],
+  ["rightbar.enabled", { type: ["boolean"] }],
+  ["rightbar.widgets", { items: widgetItems }],
+  ["profiles.*.path", { type: ["string", "null"], defaultValue: null, normalizer: "root_relative_path", validator: "nullable_non_empty_string" }],
+  ["profiles.*.active_menu", { type: ["string", "null"], defaultValue: null, validator: "nullable_kebab_id" }],
+  ["profiles.*.topbar.enabled", { type: ["boolean", "null"], defaultValue: null }],
+  ["profiles.*.topbar.brand", inheritedRegionBrand(brandProperties)],
+  ["profiles.*.topbar.menu", { type: ["array", "null"], defaultValue: null, validator: "menu_items", items: menuItem }],
+  ["profiles.*.topbar.widgets", { type: ["array", "null"], defaultValue: null, items: widgetItems }],
+  ["profiles.*.leftbar.enabled", { type: ["boolean", "null"], defaultValue: null }],
+  ["profiles.*.leftbar.brand", inheritedRegionBrand(leftbarBrandProperties)],
+  ["profiles.*.leftbar.menu", { type: ["array", "null"], defaultValue: null, validator: "menu_items", items: menuItem }],
+  ["profiles.*.leftbar.footer.actions", { type: ["array", "null"], defaultValue: null, validator: "footer_actions", items: footerAction }],
+  ["profiles.*.leftbar.widgets", { type: ["array", "null"], defaultValue: null, items: widgetItems }],
+  ["profiles.*.rightbar.enabled", { type: ["boolean", "null"], defaultValue: null }],
+  ["profiles.*.rightbar.widgets", { type: ["array", "null"], defaultValue: null, items: widgetItems }],
+  ["profiles.*.listing_nav.tabs", { validator: "navigation_tabs", items: navigationTab }],
+  ["profiles.error.image", { type: ["string", "null"], validator: "nullable_resource" }],
+  ["profiles.settings.about.items", { items: aboutItem }],
+  ["profiles.*.comments.title", { type: ["string", "null"] }],
+  ["profiles.*.comments.id", { type: ["string", "null"], normalizer: "nullable_trimmed_string", validator: "nullable_non_empty_string" }],
+  ["profiles.*.comments.provider", { type: ["string", "null"], values: [null, "beaudar", "utterances", "giscus", "twikoo", "waline", "artalk"] }],
+  ["profiles.*.comments.options", parameterBag],
+
+  ["article.style", { values: ["tech", "story"] }],
+  ["article.paragraph_indent", { values: ["auto", "always", "never"] }],
+  ["article.listing.pinned_layout", { values: ["carousel", "flat"] }],
+  ["article.listing.card_layout", { values: ["hero", "classic"] }],
+  ["article.listing.cover_ratio", { exclusiveMinimum: 0 }],
+  ["article.listing.excerpt_length", { minimum: 0, validator: "non_negative_integer" }],
+  ["article.banner.ratio", { exclusiveMinimum: 0 }],
+  ["article.category_colors", stringRecord("css_color")],
+  ["article.footer.license", { type: ["boolean", "string"], validator: "license_value" }],
+  ["article.footer.share", { items: item("string", { defaultValue: "", values: SHARE_SERVICE_IDS }), normalizer: "trimmed_string_list" }],
+  ["article.related_posts_limit", { minimum: 0, validator: "non_negative_integer" }],
+  ["profiles.notebook.listing.excerpt_length", { minimum: 0, validator: "non_negative_integer" }],
+  ["profiles.notebook.listing.per_page", { type: ["number", "null"], minimum: 0, validator: "nullable_non_negative_integer" }],
+  ["profiles.notebook.listing.sort.field", { values: ["date", "updated", "title"] }],
+  ["profiles.notebook.listing.sort.direction", { values: ["asc", "desc"] }],
+  ["profiles.notebook.tag_icons", { ...stringRecord(), validator: "non_empty_record_keys" }],
+
+  ["appearance.preset", { values: ["card", "glass", "minimal", "flat"] }],
+  ["appearance.color_scheme", { values: ["auto", "light", "dark"] }],
+  ["appearance.typography.font_size.*", { validator: "css_length" }],
+  ["appearance.typography.font_family.*", { validator: "css_font_family" }],
+  ["appearance.typography.content_align", { values: ["left", "center", "right", "justify"] }],
+  ["appearance.shape.corner", { validator: "corner_shape" }],
+  ["appearance.shape.radius.*", { validator: "css_length" }],
+  ["appearance.colors.*", { validator: "css_color" }],
+  ["appearance.gradients.*", { validator: "css_gradient" }],
+  ["appearance.code_block.scrollbar_width", { validator: "css_length" }],
+  ["appearance.code_block.highlight_stylesheet", { type: ["string", "null"], validator: "nullable_resource" }],
+  ["appearance.backgrounds.leftbar.type", { values: ["none", "gradient", "image"], normalizer: "leftbar_background_type" }],
+  ["appearance.backgrounds.leftbar.image", { type: ["string", "null"], validator: "nullable_resource" }],
+  ["appearance.backgrounds.leftbar.gradient.*", { validator: "sidebar_gradient_colors", items: item("string", { defaultValue: "" }) }],
+  ["appearance.backgrounds.leftbar.opacity", { minimum: 0, maximum: 1 }],
+  ["appearance.backgrounds.leftbar.backdrop.radius", { validator: "css_length" }],
+  ["appearance.backgrounds.page.image", { type: ["string", "null"], validator: "nullable_resource" }],
+  ["appearance.backgrounds.page.backdrop.radius", { validator: "css_length" }],
+  ["appearance.backgrounds.page.backdrop.overlay", { validator: "css_color" }],
+  ["appearance.backgrounds.page.backdrop.saturation", { validator: "css_percentage" }],
+
+  ["canonical.host", { type: ["string", "null"], normalizer: "nullable_host" }],
+  ["canonical.allowed_hosts", { items: item("string", { defaultValue: "" }), normalizer: "host_list" }],
+  ["open_graph.twitter_id", { type: ["string", "null"] }],
+  ["structured_data.same_as", { items: item("string", { defaultValue: "" }), normalizer: "trimmed_string_list" }],
+  ["preconnect", { items: item("string", { defaultValue: "" }), normalizer: "origin_list" }],
+  ["fallbacks.*", { validator: "resource" }],
+
+  ["search.provider", { type: ["string", "null"], values: [null, "local", "algolia"] }],
+  ["search.local.cache_ttl_seconds", { minimum: 0, validator: "non_negative_integer" }],
+  ["search.algolia", parameterBag],
+  ["comments.provider", { type: ["string", "null"], values: [null, "beaudar", "utterances", "giscus", "twikoo", "waline", "artalk"] }],
+  ["comments.title", { type: ["string", "null"] }],
+  ...["beaudar", "utterances", "giscus", "twikoo", "waline", "artalk"].map(id => [`comments.${id}`, parameterBag]),
+  ["tags.quot", {
+    normalizer: "object",
+    sealed: false,
+    additionalPropertyKey: "<variant>",
+    additionalProperties: item("object", {
+      defaultValue: {}, normalizer: "object", sealed: true,
+      properties: {
+        prefix: item(["string", "null"], { defaultValue: null }),
+        suffix: item(["string", "null"], { defaultValue: null })
+      }
+    })
+  }],
+  ["tags.emoji", { validator: "emoji_sources" }],
+  ["tags.emoji.default_source", { validator: "non_empty_string" }],
+  ["tags.emoji.sources", stringRecord("emoji_template")],
+  ["tags.icon.default_color", { type: ["string", "null"] }],
+  ["tags.button.default_color", { type: ["string", "null"] }],
+  ["tags.hashtag.default_color", { type: ["string", "null"] }],
+  ["tags.gallery.size", { values: ["s", "m", "l", "xl", "mix"] }],
+  ["tags.gallery.aspect_ratio", { values: ["original", "square", "portrait"] }],
+  ["features.lazy_loading.transition", { values: ["blur", "fade"] }],
+  ["features.lightbox.selector", { validator: "css_selector" }],
+  ["features.math.provider", { type: ["string", "null"], values: [null, "katex", "mathjax"] }],
+  ["features.math.katex", parameterBag],
+  ["features.math.mathjax", parameterBag],
+  ["features.diagrams.provider", { type: ["string", "null"], values: [null, "mermaid"] }],
+  ["features.diagrams.mermaid.theme", { values: ["default", "dark", "forest", "neutral"] }],
+  ["services.site_info.provider", { type: ["string", "null"], values: [null, "site_info_api"] }],
+  ["services.site_info.site_info_api", { runtimeKey: "site_info_api" }],
+  ["services.rating.provider", { type: ["string", "null"], values: [null, "star_vote"] }],
+  ["services.rating.star_vote", { runtimeKey: "star_vote" }],
+  ["services.vote.provider", { type: ["string", "null"], values: [null, "star_vote"] }],
+  ["services.vote.star_vote", { runtimeKey: "star_vote" }],
+  ["services.contributors.provider", { values: ["github"] }],
+  ["services.contributors.github.repositories", { validator: "contributor_repositories", items: contributorRepository }],
+  ["services.github.*", { validator: "absolute_http_url" }],
+  ["services.github_card.provider", { values: ["github_readme_stats"] }],
+  ["services.github_card.github_readme_stats", { runtimeKey: "github_readme_stats" }],
+  ["services.*.*.endpoint", { validator: "absolute_http_url" }],
+  ["inject.head_begin", { normalizer: "trusted_text" }],
+  ["inject.head_end", { normalizer: "trusted_text" }],
+  ["inject.body_begin", { normalizer: "trusted_text" }],
+  ["inject.body_end", { normalizer: "trusted_text" }]
+]);
+
+module.exports = {
+  CONFIG_RULES,
+  literal
+};

package/scripts/schema/config-schema.js

@@ -0,0 +1,163 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const yaml = require("js-yaml");
+
+const { deepFreeze } = require("./schema-utils");
+const { CONFIG_RULES, literal } = require("./config-rules");
+
+const DEFAULT_CONFIG_PATH = path.resolve(__dirname, "../../_config.yml");
+const LEGACY_THEME_ROOTS = Object.freeze({
+  stellar: null,
+  logo: "leftbar.brand",
+  menubar: "leftbar.menu",
+  site_tree: "profiles",
+  tag_plugins: "tags",
+  dependencies: "features.lazy_loading",
+  data_services: "services",
+  data_cache: null,
+  plugins: "features",
+  style: "appearance",
+  notebook: "profiles.notebook",
+  default: "fallbacks | profiles.error.image",
+  api_host: "services.github | services.github_card",
+  system: null
+});
+
+function isPlainObject(value) {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function clone(value) {
+  if (Array.isArray(value)) return value.map(clone);
+  if (!isPlainObject(value)) return value;
+  return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, clone(child)]));
+}
+
+function valueType(value) {
+  if (Array.isArray(value)) return "array";
+  if (value === null) return "null";
+  return typeof value;
+}
+
+function normalizerFor(type) {
+  if (type === "object") return "object";
+  if (type === "array") return "array";
+  return "identity";
+}
+
+function runtimeKey(key) {
+  return key.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
+function segments(pattern) {
+  return pattern.split(".");
+}
+
+function patternMatches(pattern, configPath) {
+  const expected = segments(pattern);
+  const actual = segments(configPath);
+  return expected.length === actual.length && expected.every((part, index) => part === "*" || part === actual[index]);
+}
+
+function matchingRules(configPath) {
+  return CONFIG_RULES.filter(([pattern]) => patternMatches(pattern, configPath)).map(([, rule]) => rule);
+}
+
+function inferNode(value, configPath, key = "") {
+  const type = valueType(value);
+  const node = {
+    type: [type],
+    default: literal(clone(value)),
+    normalizer: normalizerFor(type),
+    ...(key ? { runtimeKey: runtimeKey(key) } : {})
+  };
+  if (type === "object") {
+    node.sealed = true;
+    node.properties = Object.fromEntries(
+      Object.entries(value).map(([childKey, child]) => [
+        childKey,
+        inferNode(child, configPath ? `${configPath}.${childKey}` : childKey, childKey)
+      ])
+    );
+  }
+  for (const rule of matchingRules(configPath)) Object.assign(node, clone(rule));
+  return node;
+}
+
+function ensureRulePath(root, pattern, rule) {
+  if (!pattern.includes("*")) return;
+  const parts = segments(pattern);
+
+  function visit(node, index, configPath) {
+    if (index === parts.length) {
+      Object.assign(node, clone(rule));
+      if (Object.prototype.hasOwnProperty.call(rule, "defaultValue")) {
+        node.default = literal(clone(rule.defaultValue));
+      }
+      delete node.defaultValue;
+      return;
+    }
+    const part = parts[index];
+    if (part === "*") {
+      for (const [childKey, child] of Object.entries(node.properties || {})) {
+        visit(child, index + 1, configPath ? `${configPath}.${childKey}` : childKey);
+      }
+      return;
+    }
+    node.properties ||= {};
+    if (!node.properties[part]) {
+      if (!Object.prototype.hasOwnProperty.call(rule, "defaultValue")) return;
+      const childPath = configPath ? `${configPath}.${part}` : part;
+      const defaultValue = index === parts.length - 1 && Object.prototype.hasOwnProperty.call(rule, "defaultValue")
+        ? clone(rule.defaultValue)
+        : {};
+      node.properties[part] = inferNode(defaultValue, childPath, part);
+    }
+    visit(node.properties[part], index + 1, configPath ? `${configPath}.${part}` : part);
+  }
+
+  visit(root, 0, "");
+}
+
+function normalizeRuleDefaults(node) {
+  if (Object.prototype.hasOwnProperty.call(node, "defaultValue")) {
+    node.default = literal(clone(node.defaultValue));
+    delete node.defaultValue;
+  }
+  for (const child of Object.values(node.properties || {})) normalizeRuleDefaults(child);
+  if (node.items) normalizeRuleDefaults(node.items);
+  if (node.additionalProperties) normalizeRuleDefaults(node.additionalProperties);
+  return node;
+}
+
+function loadDefaultConfig(source = fs.readFileSync(DEFAULT_CONFIG_PATH, "utf8")) {
+  const parsed = yaml.load(source);
+  if (!isPlainObject(parsed)) throw new TypeError("themes/stellar/_config.yml 必须是 YAML 对象");
+  return parsed;
+}
+
+function buildConfigSchema(defaultConfig = loadDefaultConfig()) {
+  const schema = inferNode(defaultConfig, "");
+  schema.sealed = true;
+  schema.removedProperties = clone(LEGACY_THEME_ROOTS);
+  for (const [pattern, rule] of CONFIG_RULES) ensureRulePath(schema, pattern, rule);
+  normalizeRuleDefaults(schema);
+  return deepFreeze(schema);
+}
+
+const CONFIG_DEFAULTS = deepFreeze(loadDefaultConfig());
+const CONFIG_SCHEMA = buildConfigSchema(CONFIG_DEFAULTS);
+
+module.exports = {
+  CONFIG_DEFAULTS,
+  CONFIG_SCHEMA,
+  DEFAULT_CONFIG_PATH,
+  buildConfigSchema,
+  literal,
+  loadDefaultConfig,
+  patternMatches
+};