valaxy 0.27.0 → 0.28.0-beta.2

package/dist/node/index.d.mts

@@ -1,16 +1,15 @@
 import { ViteSSGOptions } from 'vite-ssg';
 import * as vite from 'vite';
 import { UserConfig, InlineConfig, ViteDevServer, PluginOption, Plugin } from 'vite';
-import { D as DefaultTheme, R as RuntimeConfig, a as RedirectItem, V as ValaxyConfig, P as PartialDeep, b as ValaxyAddon, S as SiteConfig, U as UserSiteConfig } from '../shared/valaxy._i636HSR.mjs';
+import { D as DefaultTheme, R as RuntimeConfig, a as RedirectItem, V as ValaxyConfig, P as PartialDeep, b as ValaxyAddon, S as SiteConfig, U as UserSiteConfig } from '../shared/valaxy.JIuR8V4d.mjs';
 import Vue from '@vitejs/plugin-vue';
-import { Options as Options$1 } from 'beasties';
 import { Hookable } from 'hookable';
 import { PluginVisualizerOptions } from 'rollup-plugin-visualizer';
 import { presetWind4, presetAttributify, presetIcons, presetTypography } from 'unocss';
 import { VitePluginConfig } from 'unocss/vite';
 import Components from 'unplugin-vue-components/vite';
 import Markdown from 'unplugin-vue-markdown/vite';
-import Layouts from 'vite-plugin-vue-layouts';
+import Layouts from 'vite-plugin-vue-layouts-next';
 import { groupIconVitePlugin } from 'vitepress-plugin-group-icons';
 import { EditableTreeNode } from 'vue-router/unplugin';
 import Router from 'vue-router/vite';
@@ -403,10 +402,31 @@ interface MarkdownOptions extends Options {
      * @see https://katex.org/docs/options.html
      */
     katex?: KatexOptions;
+    /**
+     * Options for `markdown-it-mathjax3`
+     * @see https://github.com/tani/markdown-it-mathjax3
+     */
+    mathjax?: any;
     externalLinks?: Record<string, string>;
 }
 
 type HookResult = Promise<void> | void;
+interface MdAfterRenderContext {
+    route: EditableTreeNode;
+    data: Readonly<Record<string, any>>;
+    /**
+     * The final excerpt stored in `route.meta.excerpt`.
+     * - For `<!-- more -->` or auto-generated excerpts: rendered according to `excerpt_type` (HTML/text/md).
+     * - For manual frontmatter `excerpt`: used as-is (raw string, `excerpt_type` does not apply).
+     * - Empty string if no excerpt is available.
+     */
+    excerpt: string;
+    /**
+     * Raw markdown content (without frontmatter) from gray-matter.
+     */
+    content: string;
+    path: string;
+}
 interface ValaxyHooks {
     'options:resolved': () => HookResult;
     'config:init': () => HookResult;
@@ -415,9 +435,70 @@ interface ValaxyHooks {
      */
     'vue-router:extendRoute': (route: EditableTreeNode) => HookResult;
     'vue-router:beforeWriteFiles': (root: EditableTreeNode) => HookResult;
+    /**
+     * Called after a markdown page has been loaded and its frontmatter/excerpt resolved.
+     * Fires for all `.md` routes (posts, pages, collections, etc.).
+     * Provides access to the route, raw markdown content, resolved excerpt, frontmatter data, and file path.
+     * Useful for addons that need to inspect or extend page metadata (e.g., auto-generating excerpts).
+     * @see valaxy/node/plugins/vueRouter.ts extendRoute
+     */
+    'md:afterRender': (ctx: MdAfterRenderContext) => HookResult;
     'build:before': () => HookResult;
     'build:after': () => HookResult;
+    /**
+     * @experimental
+     * Called before content loaders start fetching.
+     * @see https://github.com/YunYouJun/valaxy/issues/294
+     */
+    'content:before-load': () => HookResult;
+    /**
+     * @experimental
+     * Called after all content loaders have finished and files are written to cache.
+     * @see https://github.com/YunYouJun/valaxy/issues/294
+     */
+    'content:loaded': () => HookResult;
+}
+
+interface ContentItem {
+    /**
+     * Route path relative to pages/, e.g. 'posts/my-post.md'
+     * Must end with .md
+     */
+    path: string;
+    /**
+     * Full markdown content including YAML frontmatter block
+     */
+    content: string;
+    /**
+     * Optional digest for incremental caching (skip write if unchanged)
+     */
+    digest?: string;
+}
+interface ContentLoaderContext {
+    node: ValaxyNode;
+    /** .valaxy/content/ */
+    cacheDir: string;
+    mode: 'dev' | 'build';
+}
+interface ContentLoader {
+    name: string;
+    load: (ctx: ContentLoaderContext) => Promise<ContentItem[]> | ContentItem[];
+    /**
+     * Polling interval (ms) for dev mode.
+     * undefined = no polling
+     */
+    devPollInterval?: number;
+    /**
+     * Per-item transform before writing to cache
+     */
+    transform?: (item: ContentItem) => ContentItem | Promise<ContentItem>;
 }
+/**
+ * @experimental
+ * Define a content loader for fetching content from external CMS platforms.
+ * @see https://github.com/YunYouJun/valaxy/issues/294
+ */
+declare function defineContentLoader(loader: ContentLoader): ContentLoader;
 
 interface ValaxyEntryOptions {
     /**
@@ -493,6 +574,39 @@ interface ResolvedValaxyOptions<ThemeConfig = DefaultTheme.Config> {
     };
 }
 
+/**
+ * @experimental
+ * A module to load from CDN instead of bundling
+ */
+interface CdnModule {
+    /**
+     * npm package name to externalize
+     * @example 'vue'
+     */
+    name: string;
+    /**
+     * Global variable name the library exposes on `window`
+     * Used for mapping imports to `window[global]`
+     * @example 'Vue'
+     */
+    global: string;
+    /**
+     * Full CDN URL to the UMD/IIFE script
+     * @example 'https://cdn.jsdelivr.net/npm/vue@3.5.0/dist/vue.global.prod.js'
+     */
+    url: string;
+    /**
+     * Optional CSS URL if the module requires stylesheet
+     * @example 'https://cdn.jsdelivr.net/npm/katex@0.16.0/dist/katex.min.css'
+     */
+    css?: string;
+    /**
+     * Named exports to re-export from the global variable.
+     * Required for libraries that use named exports (e.g., `import { ref } from 'vue'`).
+     * @example ['ref', 'computed', 'watch', 'createApp']
+     */
+    exports?: string[];
+}
 type ValaxyNodeConfig<ThemeConfig = DefaultTheme.Config> = ValaxyConfig<ThemeConfig> & ValaxyExtendConfig;
 type UserValaxyNodeConfig<ThemeConfig = DefaultTheme.Config> = PartialDeep<ValaxyNodeConfig<ThemeConfig>>;
 /**
@@ -531,6 +645,34 @@ interface ValaxyExtendConfig {
          * @default false
          */
         ssgForPagination: boolean;
+        /**
+         * @en FOUC (Flash of Unstyled Content) guard configuration.
+         * Prevents layout shift on first paint by hiding the page body until
+         * full CSS is loaded. Uses `body { opacity: 0 }` inline, then the
+         * main stylesheet sets `body { opacity: 1 }` to reveal content.
+         *
+         * @zh FOUC（无样式内容闪烁）防护配置。
+         * 通过在完整 CSS 加载前隐藏页面内容来防止首屏样式闪烁。
+         * 内联 `body { opacity: 0 }`，完整 CSS 加载后通过 `body { opacity: 1 }` 解锁显示。
+         */
+        foucGuard?: {
+            /**
+             * @en Enable FOUC guard. When disabled, no opacity hiding or fallback
+             * scripts will be injected.
+             * @zh 是否启用 FOUC 防护。禁用后不会注入 opacity 隐藏及兜底脚本。
+             * @default true
+             */
+            enabled?: boolean;
+            /**
+             * @en Maximum wait time (ms) before force-showing the page, as a safety
+             * fallback in case CSS fails to load. Set to `0` to disable the timeout
+             * fallback (only `window.onload` will trigger reveal).
+             * @zh 最大等待时间（毫秒），作为 CSS 加载失败时的安全兜底。
+             * 设置为 `0` 可禁用超时兜底（仅依赖 `window.onload` 触发显示）。
+             * @default 5000
+             */
+            maxDuration?: number;
+        };
     };
     /**
      * @experimental
@@ -572,12 +714,30 @@ interface ValaxyExtendConfig {
     features: {
         /**
          * enable katex for global
+         *
+         * - `true` (default): all pages render KaTeX, unless `frontmatter.katex: false`
+         * - `false`: no pages render KaTeX by default, but individual pages can opt-in via `frontmatter.katex: true`
+         *
          * @see [Example | Valaxy](https://valaxy.site/examples/katex)
          * @see https://katex.org/
          * @default true
          */
         katex: boolean;
     };
+    /**
+     * Enable MathJax3 math rendering (aligned with VitePress `markdown.math`).
+     *
+     * When enabled, MathJax3 will be used via `markdown-it-mathjax3` to render
+     * math formulas as self-contained SVG — no external CSS or fonts required.
+     *
+     * - `features.katex` and `math` are **mutually exclusive**.
+     * - When `math` is enabled, `features.katex` is automatically ignored.
+     * - `math` requires installing `markdown-it-mathjax3`: `pnpm add markdown-it-mathjax3`
+     *
+     * @see https://www.mathjax.org/
+     * @default false
+     */
+    math: boolean;
     /**
      * vite.config.ts options
      * @see https://vite.dev/
@@ -614,11 +774,11 @@ interface ValaxyExtendConfig {
      */
     components?: Parameters<typeof Components>[0];
     /**
-     * @see https://github.com/JohnCampionJr/vite-plugin-vue-layouts
+     * @see https://github.com/loicduong/vite-plugin-vue-layouts-next
      */
     layouts?: Parameters<typeof Layouts>[0];
     /**
-     * @see https://github.com/posva/unplugin-vue-router
+     * @see https://router.vuejs.org/file-based-routing/
      */
     router?: Parameters<typeof Router>[0];
     /**
@@ -707,10 +867,27 @@ interface ValaxyExtendConfig {
      */
     hooks?: Partial<ValaxyHooks>;
     /**
-     * beastiesOptions
-     * @see https://github.com/danielroe/beasties
+     * @experimental
+     * CDN externals configuration.
+     * Specify modules to load from CDN instead of bundling them.
+     * Only takes effect during `valaxy build`, not in dev mode.
+     * @see https://github.com/YunYouJun/valaxy/issues/604
+     */
+    cdn?: {
+        /**
+         * Modules to load from CDN instead of bundling
+         * @default []
+         */
+        modules?: CdnModule[];
+    };
+    /**
+     * @experimental
+     * Content loaders for fetching content from external CMS platforms.
+     * Loaded content is written as .md files to `.valaxy/content/pages/`
+     * and automatically integrated into the routing and markdown pipeline.
+     * @see https://github.com/YunYouJun/valaxy/issues/294
      */
-    beastiesOptions?: Options$1;
+    loaders?: ContentLoader[];
 }
 type ValaxyApp = ReturnType<typeof createValaxyNode>;
 
@@ -730,8 +907,22 @@ type ValaxyAddons = (ValaxyAddon | string)[] | Record<string, ValaxyAddonLike>;
 type ValaxyAddonFn<ThemeConfig = DefaultTheme.Config> = (addonOptions: ValaxyAddonResolver, valaxyOptions: ResolvedValaxyOptions<ThemeConfig>) => ValaxyNodeConfig | Promise<ValaxyNodeConfig>;
 type ValaxyAddonExport<ThemeConfig = DefaultTheme.Config> = ValaxyNodeConfig<ThemeConfig> | ValaxyAddonFn<ThemeConfig>;
 
+interface ValaxySSGOptions {
+    concurrency?: number;
+    onBeforePageRender?: (route: string, html: string) => Promise<string | void> | string | void;
+    onPageRendered?: (route: string, html: string) => Promise<string | void> | string | void;
+    onFinished?: () => Promise<void> | void;
+    includedRoutes?: (paths: string[], routes: any[]) => string[] | Promise<string[]>;
+    includeAllRoutes?: boolean;
+}
+declare function ssgBuild(valaxyApp: ValaxyNode, viteConfig?: InlineConfig, userSsgOptions?: ValaxySSGOptions): Promise<void>;
+
 declare function build(valaxyApp: ValaxyNode, viteConfig?: InlineConfig): Promise<void>;
-declare function ssgBuild(valaxyApp: ValaxyNode, viteConfig?: InlineConfig): Promise<void>;
+/**
+ * Legacy SSG build using vite-ssg (JSDOM-based).
+ * Kept as fallback for `--ssg-engine vite-ssg`.
+ */
+declare function ssgBuildLegacy(valaxyApp: ValaxyNode, viteConfig?: InlineConfig): Promise<void>;
 /**
  * post process for ssg fix extra string like `/html>` `ml>` `l>`
  * handle tasks after ssg build
@@ -813,6 +1004,20 @@ declare function defineValaxyTheme<ThemeConfig = DefaultTheme.Config>(theme: Val
 declare const defineTheme: typeof defineValaxyTheme;
 
 declare const defaultValaxyConfig: ValaxyNodeConfig;
+/**
+ * Whether MathJax is enabled (takes priority over KaTeX).
+ */
+declare function isMathJaxEnabled(config?: ValaxyNodeConfig | null): boolean;
+/**
+ * Whether KaTeX is enabled (disabled when MathJax is active).
+ */
+declare function isKatexEnabled(config?: ValaxyNodeConfig | null): boolean;
+/**
+ * Whether the KaTeX markdown-it plugin should be registered.
+ * Always true unless MathJax is active, so that per-page `frontmatter.katex: true`
+ * can work even when `features.katex` is globally `false`.
+ */
+declare function isKatexPluginNeeded(config?: ValaxyNodeConfig | null): boolean;
 /**
  * Type helper for valaxy.config.ts
  */
@@ -946,5 +1151,5 @@ declare function toAtFS(path: string): string;
 declare function resolveImportPath(importName: string, ensure?: true): Promise<string>;
 declare function resolveImportPath(importName: string, ensure?: boolean): Promise<string | undefined>;
 
-export { $t, ALL_ROUTE, EXCERPT_SEPARATOR, GLOBAL_STATE, PATHNAME_PROTOCOL_RE, ViteValaxyPlugins, build, createServer, createValaxyPlugin, customElements, defaultSiteConfig, defaultValaxyConfig, defaultViteConfig, defineAddon, defineConfig, defineSiteConfig, defineTheme, defineUnoSetup, defineValaxyAddon, defineValaxyConfig, defineValaxyTheme, encryptContent, generateClientRedirects, getGitTimestamp, getIndexHtml, getServerInfoText, isExternal, isInstalledGlobally, isPath, loadConfigFromFile, mergeValaxyConfig, mergeViteConfigs, postProcessForSSG, processValaxyOptions, resolveAddonsConfig, resolveImportPath, resolveImportUrl, resolveOptions, resolveSiteConfig, resolveSiteConfigFromRoot, resolveThemeConfigFromRoot, resolveThemeValaxyConfig, resolveUserThemeConfig, resolveValaxyConfig, resolveValaxyConfigFromRoot, ssgBuild, toAtFS, transformObject, version };
-export type { HookResult, LoadConfigFromFileOptions, ResolvedConfig, ResolvedValaxyOptions, UnoSetup, UserInputConfig, UserValaxyNodeConfig, ValaxyAddonExport, ValaxyAddonFn, ValaxyAddonLike, ValaxyAddonResolver, ValaxyAddons, ValaxyApp, ValaxyConfigExport, ValaxyConfigExtendKey, ValaxyConfigFn, ValaxyEntryOptions, ValaxyExtendConfig, ValaxyHooks, ValaxyNode, ValaxyNodeConfig, ValaxyPickConfig, ValaxyServerOptions, ValaxyTheme };
+export { $t, ALL_ROUTE, EXCERPT_SEPARATOR, GLOBAL_STATE, PATHNAME_PROTOCOL_RE, ViteValaxyPlugins, build, createServer, createValaxyPlugin, customElements, defaultSiteConfig, defaultValaxyConfig, defaultViteConfig, defineAddon, defineConfig, defineContentLoader, defineSiteConfig, defineTheme, defineUnoSetup, defineValaxyAddon, defineValaxyConfig, defineValaxyTheme, encryptContent, generateClientRedirects, getGitTimestamp, getIndexHtml, getServerInfoText, isExternal, isInstalledGlobally, isKatexEnabled, isKatexPluginNeeded, isMathJaxEnabled, isPath, loadConfigFromFile, mergeValaxyConfig, mergeViteConfigs, postProcessForSSG, processValaxyOptions, resolveAddonsConfig, resolveImportPath, resolveImportUrl, resolveOptions, resolveSiteConfig, resolveSiteConfigFromRoot, resolveThemeConfigFromRoot, resolveThemeValaxyConfig, resolveUserThemeConfig, resolveValaxyConfig, resolveValaxyConfigFromRoot, ssgBuild, ssgBuildLegacy, toAtFS, transformObject, version };
+export type { CdnModule, ContentItem, ContentLoader, ContentLoaderContext, HookResult, LoadConfigFromFileOptions, MdAfterRenderContext, ResolvedConfig, ResolvedValaxyOptions, UnoSetup, UserInputConfig, UserValaxyNodeConfig, ValaxyAddonExport, ValaxyAddonFn, ValaxyAddonLike, ValaxyAddonResolver, ValaxyAddons, ValaxyApp, ValaxyConfigExport, ValaxyConfigExtendKey, ValaxyConfigFn, ValaxyEntryOptions, ValaxyExtendConfig, ValaxyHooks, ValaxyNode, ValaxyNodeConfig, ValaxyPickConfig, ValaxyServerOptions, ValaxyTheme };

package/dist/node/index.mjs

@@ -1,4 +1,4 @@
-export { A as ALL_ROUTE, E as EXCERPT_SEPARATOR, G as GLOBAL_STATE, P as PATHNAME_PROTOCOL_RE, V as ViteValaxyPlugins, b as build, c as cli, a as createServer, d as createValaxyPlugin, e as customElements, f as defaultSiteConfig, g as defaultValaxyConfig, h as defaultViteConfig, i as defineAddon, j as defineConfig, k as defineSiteConfig, l as defineTheme, m as defineValaxyAddon, n as defineValaxyConfig, o as defineValaxyTheme, p as encryptContent, q as generateClientRedirects, r as getGitTimestamp, s as getIndexHtml, t as getServerInfoText, u as isExternal, v as isInstalledGlobally, w as isPath, x as loadConfigFromFile, y as mergeValaxyConfig, z as mergeViteConfigs, B as postProcessForSSG, C as processValaxyOptions, D as registerDevCommand, F as resolveAddonsConfig, H as resolveImportPath, I as resolveImportUrl, J as resolveOptions, K as resolveSiteConfig, L as resolveSiteConfigFromRoot, M as resolveThemeConfigFromRoot, N as resolveThemeValaxyConfig, O as resolveUserThemeConfig, Q as resolveValaxyConfig, R as resolveValaxyConfigFromRoot, S as run, T as ssgBuild, U as startValaxyDev, W as toAtFS, X as transformObject, Y as version } from '../shared/valaxy.DpV6HHc6.mjs';
+export { A as ALL_ROUTE, E as EXCERPT_SEPARATOR, G as GLOBAL_STATE, P as PATHNAME_PROTOCOL_RE, V as ViteValaxyPlugins, b as build, c as cli, a as createServer, d as createValaxyPlugin, e as customElements, f as defaultSiteConfig, g as defaultValaxyConfig, h as defaultViteConfig, i as defineAddon, j as defineConfig, k as defineSiteConfig, l as defineTheme, m as defineValaxyAddon, n as defineValaxyConfig, o as defineValaxyTheme, p as encryptContent, q as generateClientRedirects, r as getGitTimestamp, s as getIndexHtml, t as getServerInfoText, u as isExternal, v as isInstalledGlobally, w as isKatexEnabled, x as isKatexPluginNeeded, y as isMathJaxEnabled, z as isPath, B as loadConfigFromFile, C as mergeValaxyConfig, D as mergeViteConfigs, F as postProcessForSSG, H as processValaxyOptions, I as registerDevCommand, J as resolveAddonsConfig, K as resolveImportPath, L as resolveImportUrl, M as resolveOptions, N as resolveSiteConfig, O as resolveSiteConfigFromRoot, Q as resolveThemeConfigFromRoot, R as resolveThemeValaxyConfig, S as resolveUserThemeConfig, T as resolveValaxyConfig, U as resolveValaxyConfigFromRoot, W as run, X as ssgBuild, Y as ssgBuildLegacy, Z as startValaxyDev, _ as toAtFS, $ as transformObject, a0 as version } from '../shared/valaxy.DXqMwOZX.mjs';
 import 'node:path';
 import 'fs-extra';
 import 'consola/utils';
@@ -29,13 +29,9 @@ import 'feed';
 import 'markdown-it';
 import 'table';
 import 'hookable';
+import 'node:child_process';
+import 'node:v8';
 import 'vite-ssg-sitemap';
-import 'vite-ssg/node';
-import '@intlify/unplugin-vue-i18n/vite';
-import '@unhead/addons/vite';
-import 'unplugin-vue-components/vite';
-import 'vite-plugin-vue-layouts';
-import 'vitepress-plugin-group-icons';
 import 'markdown-it-async';
 import '@shikijs/transformers';
 import 'shiki';
@@ -46,21 +42,30 @@ import 'markdown-it-emoji';
 import 'markdown-it-footnote';
 import 'markdown-it-image-figures';
 import 'markdown-it-task-lists';
+import 'vitepress-plugin-group-icons';
 import 'node:url';
 import 'markdown-it-container';
 import 'katex';
+import 'katex/contrib/mhchem';
 import 'unplugin-vue-markdown/vite';
 import 'js-base64';
+import '@intlify/unplugin-vue-i18n/vite';
+import '@unhead/addons/vite';
+import 'unplugin-vue-components/vite';
+import 'vite-plugin-vue-layouts-next';
+import 'p-map';
+import 'node:buffer';
+import 'minisearch';
+import 'lru-cache';
 import 'node:fs';
 import 'jiti';
 import 'unocss';
 import 'pascalcase';
-import 'lru-cache';
 import 'html-to-text';
 import 'vue-router/vite';
+import '@unhead/vue/server';
 import '@clack/prompts';
 import 'node:net';
-import 'node:child_process';
 import 'node:readline';
 import 'qrcode';
 import 'ejs';
@@ -73,4 +78,8 @@ function defineUnoSetup(fn) {
   return fn;
 }
 
-export { $t, defineUnoSetup };
+function defineContentLoader(loader) {
+  return loader;
+}
+
+export { $t, defineContentLoader, defineUnoSetup };