valaxy 0.28.0-beta.7 → 0.28.1

package/client/components/.exclude/ValaxyDebug.vue

@@ -0,0 +1,176 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { useRoute } from 'vue-router'
+import { useFrontmatter } from '../../composables/common'
+import { useScreenSize } from '../../composables/helper/useScreenSize'
+import { useLayout } from '../../composables/layout'
+import { useSiteConfig, useThemeConfig } from '../../config'
+import ValaxySvgLogo from '../ValaxySvgLogo.vue'
+
+const show = ref(true)
+const expanded = ref<Record<string, boolean>>({
+  breakpoints: true,
+  route: false,
+  frontmatter: false,
+  config: false,
+})
+
+function toggleSection(key: string) {
+  expanded.value[key] = !expanded.value[key]
+}
+
+// Breakpoints
+const screenSize = useScreenSize()
+const breakpoints = computed(() => [
+  { label: 'xs', value: screenSize.isXs.value },
+  { label: 'sm', value: screenSize.isSm.value },
+  { label: 'md', value: screenSize.isMd.value },
+  { label: 'lg', value: screenSize.isLg.value },
+  { label: 'xl', value: screenSize.isXl.value },
+  { label: '2xl', value: screenSize.is2xl.value },
+])
+
+// Route
+const route = useRoute()
+const routeInfo = computed(() => ({
+  path: route.path,
+  name: route.name as string,
+  layout: route.meta?.layout || 'default',
+  query: Object.keys(route.query).length ? route.query : undefined,
+  params: Object.keys(route.params).length ? route.params : undefined,
+}))
+
+// Frontmatter
+const frontmatter = useFrontmatter()
+const fmSummary = computed(() => {
+  const fm = frontmatter.value
+  if (!fm || !Object.keys(fm).length)
+    return null
+  return fm
+})
+
+// Config
+const siteConfig = useSiteConfig()
+const themeConfig = useThemeConfig()
+const layout = useLayout()
+
+const configSummary = computed(() => ({
+  theme: siteConfig.value.lang ? undefined : undefined,
+  lang: siteConfig.value.lang,
+  title: siteConfig.value.title,
+  url: siteConfig.value.url,
+  layout: layout.value,
+}))
+</script>
+
+<template>
+  <div
+    v-if="show"
+    class="valaxy-debug fixed bottom-4 left-2 z-9999 max-h-[80vh] w-72 overflow-y-auto rounded-lg bg-black/80 p-3 text-xs text-white shadow-lg backdrop-blur-sm"
+    @click.stop
+  >
+    <!-- Header -->
+    <div class="mb-2 flex items-center justify-between border-b border-white/20 pb-2">
+      <span class="flex items-center gap-1 font-bold text-cyan-400">
+        <ValaxySvgLogo class="size-4" />
+        Valaxy Debug
+      </span>
+      <button
+        class="rounded px-1 text-white/60 transition hover:bg-white/20 hover:text-white"
+        title="Close"
+        @click="show = false"
+      >
+        ✕
+      </button>
+    </div>
+
+    <!-- Breakpoints -->
+    <div class="mb-1">
+      <button
+        class="w-full rounded px-1 py-0.5 text-left font-bold text-emerald-400 transition hover:bg-white/10"
+        @click="toggleSection('breakpoints')"
+      >
+        {{ expanded.breakpoints ? '▾' : '▸' }} Breakpoints
+      </button>
+      <div v-if="expanded.breakpoints" class="mt-1 flex flex-wrap gap-1 pl-3">
+        <span
+          v-for="bp in breakpoints"
+          :key="bp.label"
+          class="rounded px-1.5 py-0.5"
+          :class="bp.value ? 'bg-emerald-500/30 text-emerald-300' : 'bg-white/5 text-white/40'"
+        >
+          {{ bp.label }}
+        </span>
+      </div>
+    </div>
+
+    <!-- Route -->
+    <div class="mb-1">
+      <button
+        class="w-full rounded px-1 py-0.5 text-left font-bold text-blue-400 transition hover:bg-white/10"
+        @click="toggleSection('route')"
+      >
+        {{ expanded.route ? '▾' : '▸' }} Route
+      </button>
+      <div v-if="expanded.route" class="mt-1 space-y-0.5 pl-3">
+        <div><span class="text-white/50">path:</span> {{ routeInfo.path }}</div>
+        <div><span class="text-white/50">name:</span> {{ routeInfo.name }}</div>
+        <div><span class="text-white/50">layout:</span> {{ routeInfo.layout }}</div>
+        <div v-if="routeInfo.query">
+          <span class="text-white/50">query:</span> {{ JSON.stringify(routeInfo.query) }}
+        </div>
+        <div v-if="routeInfo.params">
+          <span class="text-white/50">params:</span> {{ JSON.stringify(routeInfo.params) }}
+        </div>
+      </div>
+    </div>
+
+    <!-- Frontmatter -->
+    <div class="mb-1">
+      <button
+        class="w-full rounded px-1 py-0.5 text-left font-bold text-amber-400 transition hover:bg-white/10"
+        @click="toggleSection('frontmatter')"
+      >
+        {{ expanded.frontmatter ? '▾' : '▸' }} Frontmatter
+      </button>
+      <div v-if="expanded.frontmatter" class="mt-1 pl-3">
+        <pre v-if="fmSummary" class="max-h-48 overflow-auto whitespace-pre-wrap break-all rounded bg-white/5 p-1.5 text-white/80">{{ JSON.stringify(fmSummary, null, 2) }}</pre>
+        <span v-else class="text-white/40">No frontmatter</span>
+      </div>
+    </div>
+
+    <!-- Config -->
+    <div class="mb-1">
+      <button
+        class="w-full rounded px-1 py-0.5 text-left font-bold text-purple-400 transition hover:bg-white/10"
+        @click="toggleSection('config')"
+      >
+        {{ expanded.config ? '▾' : '▸' }} Config
+      </button>
+      <div v-if="expanded.config" class="mt-1 space-y-2 pl-3">
+        <div>
+          <div class="mb-0.5 text-white/50">
+            Site Config
+          </div>
+          <pre class="max-h-48 overflow-auto whitespace-pre-wrap break-all rounded bg-white/5 p-1.5 text-white/80">{{ JSON.stringify(configSummary, null, 2) }}</pre>
+        </div>
+        <div>
+          <div class="mb-0.5 text-white/50">
+            Theme Config
+          </div>
+          <pre class="max-h-48 overflow-auto whitespace-pre-wrap break-all rounded bg-white/5 p-1.5 text-white/80">{{ JSON.stringify(themeConfig, null, 2) }}</pre>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <!-- Collapsed toggle button -->
+  <button
+    v-if="!show"
+    class="fixed bottom-4 left-2 z-9999 rounded-lg bg-black/60 px-2 py-1 text-xs text-white/60 shadow-lg backdrop-blur-sm transition hover:bg-black/80 hover:text-white"
+    title="Open Valaxy Debug"
+    @click="show = true"
+  >
+    <ValaxySvgLogo class="size-4" />
+  </button>
+</template>

package/client/components/ValaxyOpenInEditor.vue

@@ -0,0 +1,53 @@
+<script lang="ts" setup>
+import { useData } from '../composables'
+
+const { page } = useData()
+
+const isDev = import.meta.env.DEV
+
+/**
+ * Open the current page source file in editor (dev mode only)
+ * Uses Vite's built-in `/__open-in-editor` endpoint
+ */
+function openInEditor() {
+  const filePath = page.value?.filePath
+  if (filePath) {
+    fetch(`${window.location.origin}/__open-in-editor?file=${encodeURIComponent(filePath)}`)
+      .catch((err) => {
+        console.error('[valaxy] Failed to open in editor:', err)
+      })
+  }
+}
+</script>
+
+<template>
+  <button
+    v-if="isDev"
+    class="valaxy-open-in-editor"
+    title="Open in Editor"
+    @click="openInEditor"
+  >
+    <slot>
+      <div i-ri-code-s-slash-line />
+    </slot>
+  </button>
+</template>
+
+<style>
+.valaxy-open-in-editor {
+  display: inline-flex;
+  align-items: center;
+  cursor: pointer;
+  opacity: 0.4;
+  transition: opacity 0.2s;
+  background: none;
+  border: none;
+  padding: 0;
+  color: inherit;
+  font-size: inherit;
+}
+
+.valaxy-open-in-editor:hover {
+  opacity: 1;
+}
+</style>

package/client/composables/app/useValaxyApp.ts

@@ -1,12 +1,8 @@
 import { definePerson, defineWebPage, defineWebSite, useSchemaOrg } from '@unhead/schema-org/vue'
 import { useSeoMeta } from '@unhead/vue'
-
-// TODO: add docs to override ValaxyApp
 import { computed } from 'vue'
 import { useI18n } from 'vue-i18n'
-
 import { useRoute } from 'vue-router'
-
 import { useFrontmatter, useLocale, useValaxyHead, useValaxyI18n } from '../../composables'
 import { useTimezone } from '../../composables/global'
 // https://github.com/vueuse/head
@@ -16,7 +12,6 @@ import { useSiteConfig } from '../../config'
 
 export function useValaxyApp() {
   const siteConfig = useSiteConfig()
-  // todo, allow user config
   const fm = useFrontmatter()
 
   const { locale } = useI18n()
@@ -32,7 +27,6 @@ export function useValaxyApp() {
   }
 
   // seo
-  // todo: get first image url from markdown
   const siteUrl = computed(() => fm.value.url || siteConfig.value.url)
   const description = computed(() => $tO(fm.value.excerpt) || $tO(fm.value.description) || $t(siteConfig.value.description))
 
@@ -43,7 +37,7 @@ export function useValaxyApp() {
     ogLocaleAlternate: computed(() => siteConfig.value.languages.filter(l => l !== locale.value)),
     ogSiteName: computed(() => $t(siteConfig.value.title)),
     ogTitle: computed(() => $tO(fm.value.title) || $t(siteConfig.value.title)),
-    ogImage: computed(() => fm.value.ogImage || fm.value.cover || siteConfig.value.favicon),
+    ogImage: computed(() => fm.value.ogImage || fm.value.cover || fm.value.firstImage || siteConfig.value.favicon),
     ogType: 'website',
     ogUrl: siteUrl,
   })

package/client/composables/categories.ts

@@ -1,47 +1,11 @@
 import type { MaybeRef } from 'vue'
 import type { Post } from '../../types'
+import type { CategoryList } from './category-utils'
 import { computed, unref } from 'vue'
 import { useSiteStore } from '../stores'
 
-/**
- * 基础分类
- */
-export interface BaseCategory {
-  /**
-   * 分类下的文章数量
-   */
-  total: number
-}
-
-/**
- * @en
- * Category list
- *
- * @zh
- * 分类列表
- */
-export interface CategoryList {
-  /**
-   * category name
-   */
-  name: string
-  /**
-   * total posts
-   */
-  total: number
-  children: Map<string, Post | CategoryList>
-}
-export type Category = CategoryList
-export type Categories = Map<string, Post | CategoryList>
-
-/**
- * For theme development, you can use this function to determine whether the category is a category list.
- * @todo write unit test
- * @param category
- */
-export function isCategoryList(category: any): category is CategoryList {
-  return category.children
-}
+export type { BaseCategory, Categories, Category, CategoryList } from './category-utils'
+export { isCategoryList, removeItemFromCategory } from './category-utils'
 
 /**
  * get categories from posts
@@ -158,20 +122,3 @@ export function useCategories(category?: MaybeRef<string>, posts: Post[] = []) {
     }
   })
 }
-
-/**
- * remove item from category
- * @param categoryList
- * @param categoryName
- */
-export function removeItemFromCategory(categoryList: CategoryList, categoryName: string) {
-  if (isCategoryList(categoryList)) {
-    const categoryArr = categoryName.split('/')
-    categoryList.children.delete(categoryArr[0])
-  }
-}
-
-/**
- * @deprecated use `useCategories` instead
- */
-export const useCategory = useCategories

package/client/composables/category-utils.ts

@@ -0,0 +1,50 @@
+import type { Post } from '../../types'
+
+/**
+ * 基础分类
+ */
+export interface BaseCategory {
+  /**
+   * 分类下的文章数量
+   */
+  total: number
+}
+
+/**
+ * @en
+ * Category list
+ *
+ * @zh
+ * 分类列表
+ */
+export interface CategoryList {
+  /**
+   * category name
+   */
+  name: string
+  /**
+   * total posts
+   */
+  total: number
+  children: Map<string, Post | CategoryList>
+}
+export type Category = CategoryList
+export type Categories = Map<string, Post | CategoryList>
+
+/**
+ * For theme development, you can use this function to determine whether the category is a category list.
+ * @param category
+ */
+export function isCategoryList(category: unknown): category is CategoryList {
+  return !!category && typeof category === 'object' && 'children' in category && category.children instanceof Map
+}
+
+/**
+ * remove item from category
+ * @param categoryList
+ * @param categoryName
+ */
+export function removeItemFromCategory(categoryList: CategoryList, categoryName: string) {
+  const categoryArr = categoryName.split('/')
+  categoryList.children.delete(categoryArr[0])
+}

package/client/composables/index.ts

@@ -4,6 +4,7 @@ export * from './app'
 export * from './back'
 // for classify
 export * from './categories'
+export * from './category-utils'
 export * from './collections'
 
 // common

package/client/composables/outline/anchor.ts

@@ -49,7 +49,7 @@ export function useActiveAnchor(
 
   /**
    * 长目录自动滚动
-   * @TODO add e2e test
+   * @see e2e/theme-yun/outline.spec.ts
    */
   const checkActiveLinkInViewport = () => {
     const activeLink = prevActiveLink

package/client/composables/tags.ts

@@ -51,8 +51,3 @@ export function useTags() {
     return tagMap
   })
 }
-
-/**
- * @deprecated use `useTags` instead
- */
-export const useTag = useTags

package/client/modules/components.ts

@@ -1,5 +1,6 @@
 import type { ValaxySSGContext } from '../setups'
 
+import { defineAsyncComponent } from 'vue'
 import AppLink from '../components/AppLink.vue'
 import ValaxyTranslate from '../components/builtin/ValaxyTranslate.vue'
 
@@ -10,4 +11,10 @@ import ValaxyTranslate from '../components/builtin/ValaxyTranslate.vue'
 export function registerGlobalComponents(ctx: ValaxySSGContext) {
   ctx.app.component('AppLink', AppLink)
   ctx.app.component('VT', ValaxyTranslate)
+
+  // DEV-only: register ValaxyDebug component (tree-shaken in production)
+  if (import.meta.env.DEV) {
+    const ValaxyDebug = defineAsyncComponent(() => import('../components/.exclude/ValaxyDebug.vue'))
+    ctx.app.component('ValaxyDebug', ValaxyDebug)
+  }
 }

package/client/modules/valaxy.ts

@@ -14,6 +14,7 @@ import type { PageDataPayload } from '../../types'
 import type { ValaxySSGContext } from '../setups'
 import { ensureSuffix } from '@antfu/utils'
 import { useStorage } from '@vueuse/core'
+import { nextTick, watch } from 'vue'
 import { createI18n } from 'vue-i18n'
 
 // @ts-expect-error virtual
@@ -52,11 +53,35 @@ export const i18n = createI18n({
 })
 
 export async function install({ app, router }: ValaxySSGContext, config: ComputedRef<ValaxyConfig<DefaultTheme.Config>>) {
-  const locale = useStorage('valaxy-locale', config?.value.siteConfig.lang || 'en')
-  i18n.global.locale.value = locale.value
+  const defaultLang = config?.value.siteConfig.lang || 'en'
+
+  // During SSR/SSG build **and** the initial client hydration pass we must
+  // keep the locale at `defaultLang` so that the rendered HTML matches on
+  // both sides — no hydration mismatch for any i18n-dependent attribute
+  // (title, class, text content, etc.).
+  //
+  // The stored user preference is restored **after** hydration is complete
+  // (router.isReady + nextTick) so Vue can patch the DOM normally.
+  i18n.global.locale.value = defaultLang
 
   app.use(i18n)
-  router.isReady().then(() => {
+
+  router.isReady().then(async () => {
+    // Wait for the hydration to finish before restoring the stored locale.
+    await nextTick()
+
+    const storedLocale = useStorage('valaxy-locale', defaultLang)
+
+    // Apply the stored locale (if different from default)
+    if (storedLocale.value && storedLocale.value !== i18n.global.locale.value)
+      i18n.global.locale.value = storedLocale.value
+
+    // Keep i18n locale in sync when the stored value changes later
+    watch(storedLocale, (val) => {
+      if (val)
+        i18n.global.locale.value = val
+    })
+
     handleHMR(router)
   })
 }

package/dist/node/cli/index.mjs

@@ -1,7 +1,7 @@
 import 'node:process';
 import 'yargs';
 import 'yargs/helpers';
-export { c as cli, I as registerDevCommand, W as run, Z as startValaxyDev } from '../../shared/valaxy.DAkHYbg0.mjs';
+export { c as cli, I as registerDevCommand, W as run, Z as startValaxyDev } from '../../shared/valaxy.DFTOADvQ.mjs';
 import 'node:os';
 import 'node:path';
 import 'consola';
@@ -29,6 +29,7 @@ import 'feed';
 import 'markdown-it';
 import 'table';
 import 'hookable';
+import 'node:fs';
 import 'node:child_process';
 import 'node:v8';
 import 'vite-ssg-sitemap';
@@ -57,7 +58,6 @@ import 'p-map';
 import 'node:buffer';
 import 'minisearch';
 import 'lru-cache';
-import 'node:fs';
 import 'jiti';
 import 'unocss';
 import 'pascalcase';

package/dist/node/index.d.mts

@@ -1,7 +1,7 @@
 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.JIuR8V4d.mjs';
+import { S as SiteConfig, D as DefaultTheme, R as RuntimeConfig, a as RedirectItem, V as ValaxyConfig, P as PartialDeep, b as ValaxyAddon, U as UserSiteConfig } from '../shared/valaxy.6MW2qn5T.mjs';
 import Vue from '@vitejs/plugin-vue';
 import { Hookable } from 'hookable';
 import { PluginVisualizerOptions } from 'rollup-plugin-visualizer';
@@ -445,6 +445,14 @@ interface ValaxyHooks {
     'md:afterRender': (ctx: MdAfterRenderContext) => HookResult;
     'build:before': () => HookResult;
     'build:after': () => HookResult;
+    /**
+     * Called to compute statistics (word count, reading time) for a markdown route.
+     * Default implementation uses `presetStatistics`; addons/themes can hook to override.
+     */
+    'statistics': (ctx: {
+        route: EditableTreeNode;
+        options: SiteConfig['statistics'];
+    }) => HookResult;
     /**
      * @experimental
      * Called before content loaders start fetching.
@@ -768,6 +776,12 @@ interface ValaxyExtendConfig {
          * @default true
          */
         katex: boolean;
+        /**
+         * @description:en-US Auto-extract the first image from markdown content for Open Graph fallback
+         * @description:zh-CN 自动从 Markdown 内容中提取第一张图片，作为 Open Graph 的回退图片
+         * @default true
+         */
+        extractFirstImage: boolean;
     };
     /**
      * Enable MathJax3 math rendering (aligned with VitePress `markdown.math`).

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 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.DAkHYbg0.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.DFTOADvQ.mjs';
 import 'node:path';
 import 'fs-extra';
 import 'consola/utils';
@@ -29,6 +29,7 @@ import 'feed';
 import 'markdown-it';
 import 'table';
 import 'hookable';
+import 'node:fs';
 import 'node:child_process';
 import 'node:v8';
 import 'vite-ssg-sitemap';
@@ -57,7 +58,6 @@ import 'p-map';
 import 'node:buffer';
 import 'minisearch';
 import 'lru-cache';
-import 'node:fs';
 import 'jiti';
 import 'unocss';
 import 'pascalcase';

package/dist/shared/{valaxy.JIuR8V4d.d.mts → valaxy.6MW2qn5T.d.mts}

@@ -167,6 +167,18 @@ interface PageFrontMatter extends BaseFrontMatter {
      * @description 封面图片
      */
     cover: string;
+    /**
+     * @description:en-US Open Graph image for SEO
+     * @description:zh-CN Open Graph 图片，用于 SEO
+     */
+    ogImage: string;
+    /**
+     * @protected
+     * @tutorial ⚠️ DO NOT SET MANUALLY (auto-extracted from markdown content)
+     * @description:en-US First image URL extracted from markdown content
+     * @description:zh-CN 从 Markdown 内容中自动提取的第一张图片 URL
+     */
+    firstImage: string;
     /**
      * display toc
      * @description 是否显示目录
@@ -638,10 +650,6 @@ interface SiteConfig {
          * @zh 是否启用
          */
         enable: boolean;
-        /**
-         * @deprecated will be deprecated, use search.provider instead
-         */
-        type?: SiteConfig['search']['provider'];
         /**
          * Search Type
          * - algolia: Algolia Search

package/dist/shared/{valaxy.DAkHYbg0.mjs → valaxy.DFTOADvQ.mjs}

@@ -28,7 +28,8 @@ import { Feed } from 'feed';
 import MarkdownIt from 'markdown-it';
 import { table, getBorderCharacters } from 'table';
 import { createHooks } from 'hookable';
-import { execFileSync, exec } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { execFileSync, execSync, exec } from 'node:child_process';
 import v8 from 'node:v8';
 import generateSitemap from 'vite-ssg-sitemap';
 import { createMarkdownItAsync, MarkdownItAsync } from 'markdown-it-async';
@@ -56,14 +57,13 @@ import pMap from 'p-map';
 import { Buffer as Buffer$1 } from 'node:buffer';
 import MiniSearch from 'minisearch';
 import { LRUCache } from 'lru-cache';
-import { existsSync, readFileSync } from 'node:fs';
 import { createJiti } from 'jiti';
 import { transformerDirectives, transformerVariantGroup, presetWind4, presetAttributify, presetIcons, presetTypography } from 'unocss';
 import pascalCase from 'pascalcase';
 import { convert } from 'html-to-text';
 import VueRouter from 'vue-router/vite';
 import { renderSSRHead } from '@unhead/vue/server';
-import { intro, confirm, select, outro } from '@clack/prompts';
+import { intro, confirm, isCancel, cancel, select, outro } from '@clack/prompts';
 import net from 'node:net';
 import * as readline from 'node:readline';
 import qrcode from 'qrcode';
@@ -878,7 +878,8 @@ const defaultValaxyConfig = {
     }
   },
   features: {
-    katex: true
+    katex: true,
+    extractFirstImage: true
   },
   math: false,
   cdn: {
@@ -931,8 +932,9 @@ async function resolveValaxyConfigFromRoot(root, options) {
 }
 const mergeValaxyConfig = createDefu((obj, key, value) => {
   if (isFunction(obj[key]) && isFunction(value)) {
+    const original = obj[key];
     obj[key] = function(...args) {
-      obj[key].call(this, ...args);
+      original.call(this, ...args);
       value.call(this, ...args);
     };
     return true;
@@ -1719,7 +1721,7 @@ async function setupMarkdownPlugins(md, options, base = "/") {
   return md;
 }
 
-const version = "0.28.0-beta.7";
+const version = "0.28.1";
 
 const GLOBAL_STATE = {
   valaxyApp: void 0,
@@ -3107,12 +3109,68 @@ function clearHtmlTags(str) {
   return str.replace(/<[^>]*>/g, "").replace(/\s+/g, " ");
 }
 
+function count(content) {
+  const cn = (content.match(/[\u4E00-\u9FA5]/g) || []).length;
+  const en = (content.replace(/[\u4E00-\u9FA5]/g, "").match(/[\w\u0392-\u03C9\u0400-\u04FF]+|[\u4E00-\u9FFF\u3400-\u4DBF\uF900-\uFAFF\u3040-\u309F\uAC00-\uD7AF\u0400-\u04FF]+|[\u00E4\u00C4\u00E5\u00C5\u00F6\u00D6]+/g) || []).length;
+  return {
+    cn,
+    en
+  };
+}
+function readTime({ cn, en }, options) {
+  const readingTime = cn / (options.speed.cn || 300) + en / (options.speed.en || 100);
+  return readingTime < 1 ? 1 : Math.ceil(readingTime);
+}
+function wordCount({ cn, en }) {
+  const num = cn + en;
+  if (num < 1e3)
+    return num.toString();
+  return `${Math.round(num / 100) / 10}k`;
+}
+function statistics(content, options) {
+  const countData = count(content);
+  return {
+    countData,
+    wordCount: wordCount(countData),
+    readingTime: readTime(countData, options.readTime)
+  };
+}
+function presetStatistics({
+  route,
+  options
+}) {
+  const absolutePath = route.components.get("default") || "";
+  if (existsSync(absolutePath)) {
+    const file = readFileSync(absolutePath, "utf-8");
+    const { wordCount: wordCount2, readingTime } = statistics(file, {
+      readTime: {
+        ...options.readTime,
+        speed: {
+          cn: options.readTime?.speed?.cn || 300,
+          en: options.readTime?.speed?.en || 100
+        }
+      }
+    });
+    const { frontmatter } = route.meta;
+    if (frontmatter && typeof frontmatter === "object" && !Array.isArray(frontmatter)) {
+      const fm = frontmatter;
+      if (!fm.wordCount)
+        fm.wordCount = wordCount2;
+      if (!fm.readingTime)
+        fm.readingTime = readingTime;
+    }
+  }
+}
+
 const buildHooks = [
   "build:before",
   "build:after"
 ];
 function createValaxyNode(options) {
   const hooks = createHooks();
+  hooks.hook("statistics", ({ route, options: statsOptions }) => {
+    presetStatistics({ route, options: statsOptions });
+  });
   if (typeof options.config.hooks === "object") {
     Object.keys(options.config.hooks).forEach((name) => {
       const hookName = name;
@@ -3394,10 +3452,24 @@ function inferDescription(frontmatter) {
     return description;
   return head && getHeadMetaContent(head, "description") || "";
 }
+function extractFirstImage(code) {
+  const mdImageMatch = code.match(/!\[.*?\]\((.+?)\)/);
+  if (mdImageMatch)
+    return mdImageMatch[1];
+  const htmlImageMatch = code.match(/<img\s[^>]*?src=["'](.+?)["']/);
+  if (htmlImageMatch)
+    return htmlImageMatch[1];
+  return void 0;
+}
 async function generatePageData(code, id, options) {
   const fileInfo = Valaxy.state.idMap.get(id);
   const relativePath = path.relative(options.userRoot, id);
   const fm = JSON.parse(JSON.stringify(fileInfo?.frontmatter));
+  if (options.config.features?.extractFirstImage !== false && !fm.ogImage && !fm.cover) {
+    const firstImage = extractFirstImage(code);
+    if (firstImage)
+      fm.firstImage = firstImage;
+  }
   const pageData = {
     title: fm.title || fileInfo?.title || "",
     titleTemplate: fm.titleTemplate,
@@ -3408,7 +3480,8 @@ async function generatePageData(code, id, options) {
     relativePath,
     filePath: id
   };
-  pageData.lastUpdated = await getGitTimestamp(id);
+  if (options.config.siteConfig.lastUpdated)
+    pageData.lastUpdated = await getGitTimestamp(id);
   return pageData;
 }
 
@@ -4285,59 +4358,6 @@ async function createValaxyPlugin(options, serverOptions = {}) {
   ];
 }
 
-function count(content) {
-  const cn = (content.match(/[\u4E00-\u9FA5]/g) || []).length;
-  const en = (content.replace(/[\u4E00-\u9FA5]/g, "").match(/[\w\u0392-\u03C9\u0400-\u04FF]+|[\u4E00-\u9FFF\u3400-\u4DBF\uF900-\uFAFF\u3040-\u309F\uAC00-\uD7AF\u0400-\u04FF]+|[\u00E4\u00C4\u00E5\u00C5\u00F6\u00D6]+/g) || []).length;
-  return {
-    cn,
-    en
-  };
-}
-function readTime({ cn, en }, options) {
-  const readingTime = cn / (options.speed.cn || 300) + en / (options.speed.en || 100);
-  return readingTime < 1 ? 1 : Math.ceil(readingTime);
-}
-function wordCount({ cn, en }) {
-  const num = cn + en;
-  if (num < 1e3)
-    return num.toString();
-  return `${Math.round(num / 100) / 10}k`;
-}
-function statistics(content, options) {
-  const countData = count(content);
-  return {
-    countData,
-    wordCount: wordCount(countData),
-    readingTime: readTime(countData, options.readTime)
-  };
-}
-function presetStatistics({
-  route,
-  options
-}) {
-  const absolutePath = route.components.get("default") || "";
-  if (existsSync(absolutePath)) {
-    const file = readFileSync(absolutePath, "utf-8");
-    const { wordCount: wordCount2, readingTime } = statistics(file, {
-      readTime: {
-        ...options.readTime,
-        speed: {
-          cn: options.readTime?.speed?.cn || 300,
-          en: options.readTime?.speed?.en || 100
-        }
-      }
-    });
-    const { frontmatter } = route.meta;
-    if (frontmatter && typeof frontmatter === "object" && !Array.isArray(frontmatter)) {
-      const fm = frontmatter;
-      if (!fm.wordCount)
-        fm.wordCount = wordCount2;
-      if (!fm.readingTime)
-        fm.readingTime = readingTime;
-    }
-  }
-}
-
 async function getExcerptByType(excerpt = "", type = "html", mdIt) {
   switch (type) {
     case "ai":
@@ -4416,7 +4436,7 @@ async function createRouterPlugin(valaxyApp) {
         const md = await fs.readFile(path, "utf-8");
         const { data, excerpt, content } = matter(md, matterOptions);
         const mdFm = data;
-        const lastUpdated = options.config.siteConfig.lastUpdated;
+        const lastUpdated = valaxyConfig.siteConfig.lastUpdated;
         delete mdFm.password;
         if (mdFm.gallery_password) {
           delete mdFm.gallery_password;
@@ -4454,8 +4474,7 @@ async function createRouterPlugin(valaxyApp) {
         ];
         const routerFM = {
           ...mdFm,
-          // 主题有新的字段需要主动设置
-          // @TODO 添加文档和配置项，或者反过来允许用户自行优化
+          // Normalize tags: ensure always an array for consistent consumption
           tags: typeof mdFm.tags === "string" ? [mdFm.tags] : mdFm.tags,
           // set default updated to date if not present
           updated: mdFm.updated ?? mdFm.date
@@ -4480,7 +4499,7 @@ async function createRouterPlugin(valaxyApp) {
           });
         }
         if (valaxyConfig.siteConfig.statistics.enable) {
-          presetStatistics({
+          await valaxyApp.hooks.callHook("statistics", {
             options: valaxyConfig.siteConfig.statistics,
             route
           });
@@ -5401,17 +5420,21 @@ async function getPosts(params, options) {
     return { data, content, excerpt, path: i };
   });
   const rawPosts = await Promise.all(readFilePromises);
+  const draftPosts = [];
   const filteredPosts = rawPosts.filter((p) => {
     const { data } = p;
     if (data.password)
       return false;
     if (data.draft) {
+      draftPosts.push(p.path);
       return false;
     }
     if (data.hide)
       return false;
     return true;
   });
+  if (draftPosts.length)
+    consola.log(`[rss] Skipped ${draftPosts.length} draft post(s): ${draftPosts.join(", ")}`);
   const posts = [];
   for (const rawPost of filteredPosts) {
     const { data, path, content, excerpt } = rawPost;
@@ -6080,58 +6103,185 @@ function registerCleanCommand(cli) {
   );
 }
 
-function registerDebugCommand(cli) {
-  cli.command("debug", "Debug your blog", async () => {
-    console.log();
-    consola.log("  Operating System:", colors.green(os.platform()));
-    consola.log("  Node.JS Version:", colors.green(process.version));
-    consola.log("  Valaxy Version:", colors.cyan(`v${version}`));
+function getPnpmVersion() {
+  try {
+    return execSync("pnpm --version", { encoding: "utf-8" }).trim();
+  } catch {
+    return "not found";
+  }
+}
+async function collectDebugInfo() {
+  const info = {
+    os: os.platform(),
+    arch: os.arch(),
+    node: process.version,
+    pnpm: getPnpmVersion(),
+    valaxy: version
+  };
+  try {
+    const options = await resolveOptions({ userRoot: process.cwd() });
+    info.userRoot = options.userRoot;
+    info.theme = options.theme;
+    info.themeVersion = options.config.themeConfig?.pkg?.version;
+    info.addons = options.addons.filter((a) => a.enable).map((a) => ({
+      name: a.name,
+      version: a.pkg?.version || "unknown",
+      global: a.global
+    }));
+    info.pages = options.pages.length;
+  } catch {
+  }
+  return info;
+}
+function printFancy(info) {
+  const lines = [];
+  lines.push(`${colors.bold(colors.cyan("Environment"))}`);
+  lines.push(`  OS:              ${colors.green(`${info.os} ${info.arch}`)}`);
+  lines.push(`  Node.js:         ${colors.green(info.node)}`);
+  lines.push(`  Package Manager: ${colors.green(`pnpm ${info.pnpm}`)}`);
+  lines.push(`  Valaxy:          ${colors.cyan(`v${info.valaxy}`)}`);
+  if (info.theme) {
+    lines.push("");
+    lines.push(`${colors.bold(colors.cyan("Project"))}`);
+    lines.push(`  Root:   ${colors.dim(info.userRoot)}`);
+    lines.push(`  Theme:  ${colors.green(info.theme)} ${colors.blue(`v${info.themeVersion || "unknown"}`)}`);
+    if (info.addons && info.addons.length > 0) {
+      lines.push(`  Addons:`);
+      info.addons.forEach((addon, i) => {
+        const prefix = i === info.addons.length - 1 ? "\u2514\u2500" : "\u251C\u2500";
+        const globalTag = addon.global ? colors.cyan(" (global)") : "";
+        lines.push(`    ${prefix} ${colors.yellow(addon.name)} ${colors.blue(`v${addon.version}`)}${globalTag}`);
+      });
+    } else {
+      lines.push(`  Addons:  ${colors.dim("none")}`);
+    }
+    lines.push(`  Pages:  ${colors.green(String(info.pages))}`);
+  }
+  consola.box({
+    title: "\u{1F30C} Valaxy Debug Info",
+    message: lines.join("\n"),
+    style: {
+      borderColor: "cyan"
+    }
   });
 }
+function printPlain(info) {
+  const lines = [];
+  lines.push("## Environment");
+  lines.push(`- OS: ${info.os} ${info.arch}`);
+  lines.push(`- Node: ${info.node}`);
+  lines.push(`- Package Manager: pnpm ${info.pnpm}`);
+  lines.push(`- Valaxy: v${info.valaxy}`);
+  if (info.theme) {
+    lines.push("");
+    lines.push("## Project");
+    lines.push(`- Root: ${info.userRoot}`);
+    lines.push(`- Theme: ${info.theme} (v${info.themeVersion || "unknown"})`);
+    if (info.addons && info.addons.length > 0) {
+      const addonStr = info.addons.map((a) => `${a.name} (v${a.version})${a.global ? " [global]" : ""}`).join(", ");
+      lines.push(`- Addons: ${addonStr}`);
+    } else {
+      lines.push("- Addons: none");
+    }
+    lines.push(`- Pages: ${info.pages}`);
+  }
+  console.log(lines.join("\n"));
+}
+function registerDebugCommand(cli) {
+  cli.command(
+    "debug",
+    "Display debug information for your Valaxy project",
+    (args) => args.option("plain", {
+      type: "boolean",
+      default: false,
+      describe: "Output plain text without colors (for pasting into issues)"
+    }),
+    async (args) => {
+      const info = await collectDebugInfo();
+      if (args.plain)
+        printPlain(info);
+      else
+        printFancy(info);
+    }
+  );
+}
 
 function registerDeployCommand(cli) {
-  cli.command("deploy", "deploy your blog to the cloud", async () => {
-    intro("Deploying Your Blog");
-    const shouldBuild = await confirm({
-      message: "Do you want to build your blog before deploying?"
-    });
-    if (shouldBuild) {
-      await execBuild({ ssg: true, ssgEngine: "valaxy", root: process.cwd(), output: "dist", log: "info" });
-    }
-    const deployType = await select({
-      message: "Where do you want to deploy?",
-      options: [
-        { label: "GitHub Pages", value: "gh-pages", hint: "You need install `gh-pages` dependencies." },
-        { label: "Your Own Server", value: "server" }
-      ]
-    });
-    if (deployType === "gh-pages") {
-      let isGhPagesInstalled = false;
-      try {
-        await import('gh-pages');
-        isGhPagesInstalled = true;
-      } catch (e) {
-        console.error(e);
-        const installGhPages = await confirm({
-          message: "Do you want to install `gh-pages` now?"
-        });
-        if (installGhPages) {
-          await import('@antfu/install-pkg').then((i) => i.installPackage("gh-pages", { dev: true }));
+  cli.command(
+    "deploy [root]",
+    "deploy your blog to the cloud",
+    (args) => commonOptions(args).option("type", {
+      type: "string",
+      choices: ["gh-pages", "remote"],
+      describe: "deploy type, overrides `deploy.type` in config"
+    }).option("output", {
+      alias: "o",
+      type: "string",
+      default: "dist",
+      describe: "output dir"
+    }).strict().help(),
+    async ({ root, type, output }) => {
+      intro("Deploying Your Blog");
+      const shouldBuild = await confirm({
+        message: "Do you want to build your blog before deploying?"
+      });
+      if (isCancel(shouldBuild)) {
+        cancel("Operation cancelled.");
+        process.exit(0);
+      }
+      if (shouldBuild) {
+        await execBuild({ ssg: true, ssgEngine: "valaxy", root, output, log: "info" });
+      }
+      const options = await resolveOptions({ userRoot: root }, "build");
+      const configDeployType = type ?? options.config.deploy?.type;
+      const deployType = configDeployType ?? await select({
+        message: "Where do you want to deploy?",
+        options: [
+          { label: "GitHub Pages", value: "gh-pages", hint: "You need install `gh-pages` dependencies." },
+          { label: "Your Own Server", value: "remote" }
+        ]
+      });
+      if (isCancel(deployType)) {
+        cancel("Operation cancelled.");
+        process.exit(0);
+      }
+      if (deployType === "gh-pages") {
+        let isGhPagesInstalled = false;
+        try {
+          await import('gh-pages');
           isGhPagesInstalled = true;
-        } else {
-          outro("Please install `gh-pages` before deploying to GitHub Pages.");
+        } catch {
+          const installGhPages = await confirm({
+            message: "Do you want to install `gh-pages` now?"
+          });
+          if (isCancel(installGhPages)) {
+            cancel("Operation cancelled.");
+            process.exit(0);
+          }
+          if (installGhPages) {
+            try {
+              await import('@antfu/install-pkg').then((i) => i.installPackage("gh-pages", { dev: true }));
+              isGhPagesInstalled = true;
+            } catch (e) {
+              consola.error("Failed to install `gh-pages`:", e);
+            }
+          } else {
+            outro("Please install `gh-pages` before deploying to GitHub Pages.");
+          }
         }
-      }
-      if (isGhPagesInstalled) {
-        const { publish } = await import('gh-pages');
-        await publish("dist", {
-          branch: "gh-pages",
-          message: "chore: deploy by valaxy"
-        });
-        outro("Done!");
+        if (isGhPagesInstalled) {
+          const { publish } = await import('gh-pages');
+          await publish(output, {
+            branch: "gh-pages",
+            message: "chore: deploy by valaxy"
+          });
+          outro("Done!");
+        }
+      } else if (deployType === "remote") {
+        outro("Remote deployment is not yet implemented.");
       }
     }
-  });
+  );
 }
 
 async function findFreePort(start) {

package/dist/types/index.d.mts

@@ -1,5 +1,5 @@
-import { c as Post } from '../shared/valaxy.JIuR8V4d.mjs';
-export { A as Album, B as BaseFrontMatter, D as DefaultTheme, E as ExcerptType, F as FuseListItem, d as Page, e as PageFrontMatter, P as PartialDeep, f as Photo, g as Pkg, h as PostFrontMatter, a as RedirectItem, i as RedirectRule, R as RuntimeConfig, S as SiteConfig, j as SocialLink, U as UserSiteConfig, k as UserValaxyConfig, b as ValaxyAddon, V as ValaxyConfig } from '../shared/valaxy.JIuR8V4d.mjs';
+import { c as Post } from '../shared/valaxy.6MW2qn5T.mjs';
+export { A as Album, B as BaseFrontMatter, D as DefaultTheme, E as ExcerptType, F as FuseListItem, d as Page, e as PageFrontMatter, P as PartialDeep, f as Photo, g as Pkg, h as PostFrontMatter, a as RedirectItem, i as RedirectRule, R as RuntimeConfig, S as SiteConfig, j as SocialLink, U as UserSiteConfig, k as UserValaxyConfig, b as ValaxyAddon, V as ValaxyConfig } from '../shared/valaxy.6MW2qn5T.mjs';
 import { Header } from '@valaxyjs/utils';
 import '@vueuse/integrations/useFuse';
 import 'medium-zoom';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "valaxy",
   "type": "module",
-  "version": "0.28.0-beta.7",
+  "version": "0.28.1",
   "description": "📄 Vite & Vue powered static blog generator.",
   "author": {
     "email": "me@yunyoujun.cn",
@@ -57,7 +57,7 @@
     "types"
   ],
   "engines": {
-    "node": "^14.18.0 || >=16.0.0"
+    "node": "^18.0.0 || >=20.0.0"
   },
   "dependencies": {
     "@antfu/install-pkg": "^1.1.0",
@@ -95,7 +95,7 @@
     "jiti": "^2.6.1",
     "js-base64": "^3.7.8",
     "js-yaml": "^4.1.1",
-    "katex": "^0.16.40",
+    "katex": "^0.16.42",
     "lru-cache": "^11.2.7",
     "markdown-it": "^14.1.1",
     "markdown-it-anchor": "^9.2.0",
@@ -105,7 +105,7 @@
     "markdown-it-emoji": "^3.0.0",
     "markdown-it-footnote": "^4.0.0",
     "markdown-it-image-figures": "^2.1.1",
-    "markdown-it-table-of-contents": "^1.1.0",
+    "markdown-it-table-of-contents": "^1.2.0",
     "markdown-it-task-lists": "^2.1.1",
     "medium-zoom": "^1.1.0",
     "mermaid": "^11.13.0",
@@ -129,9 +129,8 @@
     "unplugin-vue-components": "28.0.0",
     "unplugin-vue-markdown": "^30.0.0",
     "vanilla-lazyload": "^19.1.3",
-    "vite": "^8.0.1",
-    "vite-dev-rpc": "^1.1.0",
-    "vite-plugin-vue-devtools": "^8.1.0",
+    "vite": "^8.0.2",
+    "vite-plugin-vue-devtools": "^8.1.1",
     "vite-plugin-vue-layouts-next": "^2.1.0",
     "vite-ssg": "^28.3.0",
     "vite-ssg-sitemap": "^0.10.0",
@@ -140,8 +139,8 @@
     "vue-i18n": "^11.3.0",
     "vue-router": "^5.0.4",
     "yargs": "^18.0.0",
-    "@valaxyjs/utils": "0.28.0-beta.7",
-    "@valaxyjs/devtools": "0.28.0-beta.7"
+    "@valaxyjs/devtools": "0.28.1",
+    "@valaxyjs/utils": "0.28.1"
   },
   "devDependencies": {
     "@mdit-vue/plugin-component": "^3.0.2",

package/types/config.ts

@@ -172,10 +172,6 @@ export interface SiteConfig {
      * @zh 是否启用
      */
     enable: boolean
-    /**
-     * @deprecated will be deprecated, use search.provider instead
-     */
-    type?: SiteConfig['search']['provider']
     /**
      * Search Type
      * - algolia: Algolia Search

package/types/frontmatter/page.ts

@@ -109,6 +109,18 @@ export interface PageFrontMatter extends BaseFrontMatter {
    * @description 封面图片
    */
   cover: string
+  /**
+   * @description:en-US Open Graph image for SEO
+   * @description:zh-CN Open Graph 图片，用于 SEO
+   */
+  ogImage: string
+  /**
+   * @protected
+   * @tutorial ⚠️ DO NOT SET MANUALLY (auto-extracted from markdown content)
+   * @description:en-US First image URL extracted from markdown content
+   * @description:zh-CN 从 Markdown 内容中自动提取的第一张图片 URL
+   */
+  firstImage: string
   /**
    * display toc
    * @description 是否显示目录