@xingwangzhe/stalux 1.23.2 → 1.24.0

package/README.md

@@ -23,34 +23,35 @@ bun add @xingwangzhe/stalux         # Install theme (all dependencies included)
 bunx stalux init                    # Generate stalux/ content directory
 ```
 
-Then configure `astro.config.mjs`:
+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 { mermaidHast } from "@xingwangzhe/satteri-mermaid";
-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(), mermaidHast({ responsive: true, theme: "dark" })],
-        }),
-    },
+    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

package/package.json

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

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,6 +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 包，需要在模块顶层导入
@@ -19,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";
@@ -212,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,
     };
 
@@ -224,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 ({
@@ -296,17 +302,33 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration {
 
                 logger.info(`Stalux initialized (contentDir: ${opt.contentDir})`);
 
-                // 5. 注入 satteri 插件（字数统计/特性标记/数学公式），按插件 name 去重
-                // 源码模式下 astro.config 会显式注册同款插件，插件模式则由集成补齐，
-                // 保证两种模式行为一致（wordCount/readingMinutes/hasImage 由构建期插件写入）。
-                // 去重是必须的：重复注册 featureFlagsMdast 会导致字数统计翻倍。
+                // 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);
@@ -318,13 +340,25 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration {
                             }
                             list.push(plugin);
                         };
+                        pushUnique(mdastPlugins, mermaidMdast());
                         pushUnique(mdastPlugins, temml());
                         pushUnique(mdastPlugins, featureFlagsMdast);
+                        pushUnique(
+                            hastPlugins,
+                            mermaidHast({
+                                responsive: true,
+                                theme: "dark",
+                                themeOverrides: { clusterBorder: "#cccccc" },
+                            }),
+                        );
+                        pushUnique(hastPlugins, photoswipe());
                         pushUnique(hastPlugins, featureFlagsHast);
-                        logger.debug("Stalux: injected satteri plugins (temml/feature-flags)");
+                        logger.debug(
+                            "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({...})`。",
                         );
                     }
@@ -436,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;