@xingwangzhe/stalux 1.23.3 → 1.24.1

package/README.md

@@ -23,33 +23,35 @@ bun add @xingwangzhe/stalux         # Install theme (all dependencies included)
 bunx stalux init                    # Generate stalux/ content directory
 ```
 
-Then configure `astro.config.mjs`. Mermaid (including MDAST detection and HAST/SVG rendering) is injected by Stalux automatically, so no manual Mermaid configuration is needed:
+Then configure `astro.config.mjs`. All plugins are bundled into the Stalux integration by default — **no manual configuration is needed**:
+
+- **Markdown**: Mermaid (MDAST detection + HAST/SVG rendering), math formulas (Temml → MathML), word count / feature flags, and PhotoSwipe image lightbox are injected into the default `satteri()` processor automatically (math / frontmatter / gfm / smart punctuation are enabled by default).
+- **Sitemap**: `@astrojs/sitemap` is bundled (`.md` source endpoints are filtered out by default).
+- **Expressive Code**: bundled with line numbers enabled by default.
 
 ```ts
 import { defineConfig } from "astro/config";
-import { satteri } from "@astrojs/markdown-satteri";
-import sitemap from "@astrojs/sitemap";
-import expressiveCode from "astro-expressive-code";
 import stalux from "@xingwangzhe/stalux";
-import { photoswipe } from "@xingwangzhe/satteri-photoswipe";
 
 export default defineConfig({
     output: "static",
     site: "https://example.com",
-    integrations: [
-        stalux({ contentDir: "stalux" }),
-        sitemap(),
-        expressiveCode({ themes: ["dark-plus", "github-light"] }),
-    ],
-    markdown: {
-        processor: satteri({
-            features: { math: true, smartPunctuation: true, gfm: true, frontmatter: true },
-            hastPlugins: [photoswipe()],
-        }),
-    },
+    integrations: [stalux({ contentDir: "stalux" })],
 });
 ```
 
+To customize the bundled integrations, pass options (or disable them with `false`):
+
+```ts
+integrations: [
+    stalux({
+        contentDir: "stalux",
+        sitemap: { filter: (page) => page.startsWith("https://example.com/posts/") },
+        expressiveCode: { themes: ["dark-plus", "github-light"] },
+    }),
+];
+```
+
 Create `src/content.config.ts`:
 
 ```ts
@@ -78,9 +80,10 @@ bun run dev
 - 🔤 **Unicode-range font slicing** — 25 MB font → ~22 woff2 chunks, browser downloads only what matches the page
 - 🔍 **Full-text search** via Pagefind (auto-indexed on build)
 - 📡 **RSS & Atom feeds**
+- 🗺️ **Sitemap** (bundled; `.md` source endpoints auto-filtered)
 - 🖼️ **PhotoSwipe** image lightbox
 - 📊 **Mermaid** diagrams and flowcharts
-- 📐 **Math formula rendering** (KaTeX / MathML)
+- 📐 **Math formula rendering** (Temml → MathML)
 - 💬 **Waline** comment system
 - 🤖 **LLM discovery files** (llms.txt / llms-full.txt)
 - 🤝 **WebMCP tools** for AI agents (W3C draft, pure front-end)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.23.3",
+    "version": "1.24.1",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",

package/src/components/stalux/posts/postContent.astro

@@ -140,7 +140,14 @@ const mdSourceUrl = exportMd
                 }
             }
 
-            let lightbox = null;
+            // 状态放 window：View Transitions 软导航会重执行模块脚本，
+            // 用全局标记避免 document 级监听器重复注册导致灯箱重复初始化。
+            const state = (window.__staluxPhotoswipe ||= {
+                lightbox: null,
+                initPromise: null,
+                lightboxInitialized: false,
+                handlerInstalled: false,
+            });
 
             async function initLightbox() {
                 const [{ default: PhotoSwipeLightbox }, { default: PhotoSwipe }, { default: photoSwipeCss }] = await Promise.all([
@@ -159,45 +166,72 @@ const mdSourceUrl = exportMd
                 }
 
                 // 销毁旧实例（View Transition 导航后，旧 DOM 已移除，需安全销毁）
-                if (lightbox) {
+                if (state.lightbox) {
                     try {
-                        lightbox.destroy();
+                        state.lightbox.destroy();
                     } catch {
                         /* ignore */
                     }
-                    lightbox = null;
+                    state.lightbox = null;
                 }
 
                 // 不阻塞文章首屏；已加载图片会立即写入尺寸，其余图片在后台补齐。
                 void enrichPhotoSwipeData();
 
-                lightbox = new PhotoSwipeLightbox({
+                state.lightbox = new PhotoSwipeLightbox({
                     gallery: "[data-pagefind-body]",
                     children: GALLERY_SELECTOR,
                     pswpModule: PhotoSwipe,
                     initialZoomLevel: "fill",
                 });
-                lightbox.init();
+                state.lightbox.init();
             }
 
-            let initPromise = null;
             const ensureLightbox = () => {
-                if (!initPromise) initPromise = initLightbox();
-                return initPromise;
+                if (!state.initPromise) state.initPromise = initLightbox();
+                return state.initPromise;
             };
 
-            // 仅在用户第一次点击图片时加载 PhotoSwipe、其 CSS 和图片尺寸数据，
-            // 文章首屏不再为未使用的灯箱支付 JS/CSS 成本。
-            document.addEventListener("click", (event) => {
+            function handleGalleryClick(event) {
                 const target = event.target;
-                if (target instanceof Element && target.closest(GALLERY_SELECTOR)) {
-                    void ensureLightbox();
-                }
-            }, { capture: true });
+                if (!(target instanceof Element && target.closest(GALLERY_SELECTOR))) return;
+
+                // 灯箱就绪后，后续点击交给 PhotoSwipeLightbox 自身的
+                // bubble 阶段处理（它负责 preventDefault + loadAndOpen）。
+                if (state.lightboxInitialized) return;
+
+                // 首次点击：立即阻止浏览器跳转到原始图片（否则会离开文章页），
+                // 异步初始化完成后直接打开被点击的图片。
+                event.preventDefault();
+                const anchor = target.closest(GALLERY_SELECTOR);
+                const clickedIndex = [...document.querySelectorAll(GALLERY_SELECTOR)].indexOf(anchor);
+                const initialPoint = { x: event.clientX, y: event.clientY };
+
+                void ensureLightbox()
+                    .then(() => {
+                        state.lightboxInitialized = true;
+                        if (state.lightbox) {
+                            state.lightbox.loadAndOpen(clickedIndex, undefined, initialPoint);
+                        }
+                    })
+                    .catch((error) => {
+                        console.error("[stalux photoswipe] 初始化失败", error);
+                    });
+            }
 
-            document.addEventListener("astro:page-load", () => {
-                initPromise = null;
-            });
+            if (!state.handlerInstalled) {
+                state.handlerInstalled = true;
+
+                // 仅在用户第一次点击图片时加载 PhotoSwipe、其 CSS 和图片尺寸数据，
+                // 文章首屏不再为未使用的灯箱支付 JS/CSS 成本。
+                document.addEventListener("click", handleGalleryClick, { capture: true });
+
+                // 软导航后旧 DOM 已移除：下次点击重新初始化（initLightbox 会销毁旧实例）。
+                document.addEventListener("astro:page-load", () => {
+                    state.initPromise = null;
+                    state.lightboxInitialized = false;
+                });
+            }
         </script>
     )
 }

package/src/config.ts

@@ -4,6 +4,9 @@
  * 用户在 astro.config.mjs 中传入这些选项来自定义主题行为。
  */
 
+import type { SitemapOptions } from "@astrojs/sitemap";
+
+import type { ExpressiveCodeOptions } from "./expressive-code";
 import type { StaluxComponentKey } from "./internal/override";
 
 /** 用户可覆盖的组件映射 */
@@ -55,4 +58,16 @@ export interface StaluxOptions {
 
     /** 站点 URL（默认从 astro.config 读取） */
     site?: string;
+
+    /**
+     * 是否自动打包 @astrojs/sitemap（默认 true）。
+     * 传 false 关闭；传对象自定义选项（filter 会与默认的 .md 源码端点过滤叠加）。
+     */
+    sitemap?: boolean | SitemapOptions;
+
+    /**
+     * 是否自动打包 Expressive Code（默认 true，带代码块行号插件）。
+     * 传 false 关闭；传对象自定义主题/样式等选项。
+     */
+    expressiveCode?: boolean | ExpressiveCodeOptions;
 }

package/src/expressive-code.ts

@@ -17,7 +17,7 @@
 import { pluginLineNumbers } from "@expressive-code/plugin-line-numbers";
 import expressiveCodeBase from "astro-expressive-code";
 
-type ExpressiveCodeOptions = NonNullable<Parameters<typeof expressiveCodeBase>[0]>;
+export type ExpressiveCodeOptions = NonNullable<Parameters<typeof expressiveCodeBase>[0]>;
 
 /**
  * 创建带默认行号插件的 Expressive Code 集成。

package/src/index.ts

@@ -12,7 +12,9 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from "
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import sitemap from "@astrojs/sitemap";
 import { mermaidMdast, mermaidHast } from "@xingwangzhe/satteri-mermaid";
+import { photoswipe } from "@xingwangzhe/satteri-photoswipe";
 import type { AstroIntegration } from "astro";
 import { fontProviders } from "astro/config";
 // pagefind 是 ESM-only 包，需要在模块顶层导入
@@ -20,6 +22,7 @@ import { fontProviders } from "astro/config";
 import { createIndex as pagefindCreateIndex } from "pagefind";
 
 import type { StaluxOptions } from "./config";
+import { expressiveCode } from "./expressive-code";
 import { staluxComponentsAlias } from "./internal/components-plugin";
 import { runFontSlicing, type FontSlice } from "./internal/font-slices";
 import { featureFlagsHast, featureFlagsMdast } from "./plugins/feature-flags";
@@ -213,11 +216,13 @@ function getViteAliases(srcDir: string) {
  * });
  * ```
  */
-export function stalux(options: StaluxOptions = {}): AstroIntegration {
+export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
     const opt: StaluxOptions = {
         contentDir: options.contentDir ?? "stalux",
         pagefind: options.pagefind ?? true,
         devToolbar: options.devToolbar ?? true,
+        sitemap: options.sitemap ?? true,
+        expressiveCode: options.expressiveCode ?? true,
         ...options,
     };
 
@@ -225,7 +230,7 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration {
     // 安装在 node_modules 中时，页面的文件路由不可用，需要通过 injectRoute 注入
     const isPluginMode = import.meta.url.includes("node_modules");
 
-    return {
+    const coreIntegration: AstroIntegration = {
         name: "stalux",
         hooks: {
             "astro:config:setup": async ({
@@ -297,16 +302,33 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration {
 
                 logger.info(`Stalux initialized (contentDir: ${opt.contentDir})`);
 
-                // 5. 注入 satteri 插件（Mermaid/字数统计/特性标记/数学公式），按插件 name 去重
-                // 两种模式都由集成补齐默认插件，消费方只需配置 Satteri 的基础 features 和自定义插件。
+                // 5. 注入 satteri 插件（Mermaid/字数统计/特性标记/数学公式/PhotoSwipe），按插件 name 去重
+                // 两种模式都由集成补齐默认插件。Astro 7 的 markdown.processor 默认为 satteri()，
+                // 消费方即使完全不配置 processor，这里也会对默认 processor 的 options 做幂等合并：
+                //   - features：默认开启 math / frontmatter / gfm / smartPunctuation（用户显式 false 则尊重）
+                //   - mdastPlugins：mermaidMdast + temml（数学公式）+ featureFlagsMdast（字数统计）
+                //   - hastPlugins：photoswipe（图片灯箱）+ mermaidHast + featureFlagsHast
                 // 去重是必须的：重复注册 Mermaid 或 featureFlagsMdast 会导致渲染异常或字数统计翻倍。
                 try {
                     const processor = (config.markdown?.processor ?? undefined) as
-                        | { name?: string; options?: { mdastPlugins?: any[]; hastPlugins?: any[] } }
+                        | {
+                              name?: string;
+                              options?: {
+                                  mdastPlugins?: any[];
+                                  hastPlugins?: any[];
+                                  features?: Record<string, unknown>;
+                              };
+                          }
                         | undefined;
                     if (processor?.name === "satteri") {
-                        const mdastPlugins = processor.options?.mdastPlugins ?? [];
-                        const hastPlugins = processor.options?.hastPlugins ?? [];
+                        const options = processor.options ?? {};
+                        const mdastPlugins = (options.mdastPlugins ??= []);
+                        const hastPlugins = (options.hastPlugins ??= []);
+                        const features = (options.features ??= {});
+                        // 默认开启 math / frontmatter / gfm / smartPunctuation
+                        for (const key of ["math", "frontmatter", "gfm", "smartPunctuation"]) {
+                            if (features[key] !== false) features[key] = true;
+                        }
                         const seen = new Set<string>();
                         for (const p of [...mdastPlugins, ...hastPlugins]) {
                             if (p?.name) seen.add(p.name);
@@ -329,13 +351,14 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration {
                                 themeOverrides: { clusterBorder: "#cccccc" },
                             }),
                         );
+                        pushUnique(hastPlugins, photoswipe());
                         pushUnique(hastPlugins, featureFlagsHast);
                         logger.debug(
-                            "Stalux: injected satteri plugins (mermaid/temml/feature-flags)",
+                            "Stalux: injected satteri plugins (mermaid/temml/photoswipe/feature-flags)",
                         );
                     } else {
                         logger.warn(
-                            "Stalux: markdown.processor 不是 satteri，无法注入字数统计/数学公式插件。" +
+                            "Stalux: markdown.processor 不是 satteri，无法注入字数统计/数学公式/PhotoSwipe 插件。" +
                                 "请在 astro.config 中配置 `processor: satteri({...})`。",
                         );
                     }
@@ -447,6 +470,33 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration {
             },
         },
     };
+
+    // 打包内置集成：Astro 的 integrations 配置支持嵌套数组并自动展平（schema 里 val.flat(Infinity)），
+    // 因此这里返回 [coreIntegration, sitemap, expressiveCode]，让消费方一行 `integrations: [stalux()]` 即可完成配置。
+    const bundled: AstroIntegration[] = [coreIntegration];
+
+    if (opt.sitemap !== false) {
+        const userSitemap = opt.sitemap === true ? undefined : opt.sitemap;
+        // 默认过滤：不把 Markdown 源码端点（/posts/*.md）写入 sitemap；用户自定义 filter 与之叠加
+        const defaultFilter = (page: string) => !page.endsWith(".md");
+        const userFilter = userSitemap?.filter;
+        const filter = userFilter
+            ? (page: string) => defaultFilter(page) && userFilter(page)
+            : defaultFilter;
+        bundled.push(
+            sitemap({
+                ...userSitemap,
+                filter,
+            }),
+        );
+    }
+
+    if (opt.expressiveCode !== false) {
+        const ecOptions = opt.expressiveCode === true ? undefined : opt.expressiveCode;
+        bundled.push(expressiveCode(ecOptions));
+    }
+
+    return bundled;
 }
 
 export default stalux;