@xingwangzhe/stalux 1.2.0 → 1.3.0

package/README.md

@@ -33,43 +33,73 @@ bun run dev           # or npm run dev
 
 ### Option B: Install as Astro Integration (Plugin Mode)
 
-Keep your project clean — install stalux as a dependency:
+Keep your project clean — install stalux as a dependency in a new or existing Astro project.
+
+**Step-by-step from scratch:**
 
 ```bash
-npm install @xingwangzhe/stalux
-```
+# 1. Create a new Astro project (choose "minimal" template)
+bun create astro
 
-Then initialize the content template:
+# 2. Enter your project directory
+cd ./myblog
 
-```bash
-npx @xingwangzhe/stalux init
-# or: npm run init
+# 3. Install the stalux theme package
+bun add @xingwangzhe/stalux
+
+# 4. Initialize content template (creates stalux/ dir with configs & sample posts)
+bunx stalux init
+
+# 5. Add required peer dependencies (for Markdown, code highlighting, etc.)
+bun add @astrojs/markdown-satteri astro-expressive-code @astrojs/sitemap
+bun add @xingwangzhe/satteri-mermaid @xingwangzhe/satteri-photoswipe
 ```
 
-This creates the `stalux/` directory structure with example content in your project. Then add to `astro.config.mjs`:
+**5. Configure `astro.config.mjs`:**
 
 ```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({
-  integrations: [stalux({
-    contentDir: "./content",     // customize content directory (default: "stalux")
-    components: {                // optional: override theme components
-      // Navs: "./src/CustomNavs.astro",
+    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" })],
+        }),
     },
-  })],
 });
 ```
 
 Create `src/content.config.ts`:
 
 ```ts
-import { defineCollections } from "stalux/schemas";
-export const collections = defineCollections({ contentDir: "./content" });
+import { defineCollections } from "@xingwangzhe/stalux/schemas";
+export const collections = defineCollections({ contentDir: "stalux" });
 ```
 
-Then write your content in `./content/posts/`, `./content/config/`, etc.
+**6. Start writing and developing:**
+
+```bash
+bun run dev
+```
+
+Your blog is now running at `http://localhost:4321/` with all theme pages, search, RSS, and more ready to go.
+
+> 💡 `bunx stalux init` creates the `stalux/` directory structure with example content.
+> Run it any time to see what a valid config looks like — it won't overwrite existing files.
 
 ---
 
@@ -157,13 +187,15 @@ import { defineConfig } from "astro/config";
 import stalux from "@xingwangzhe/stalux";
 
 export default defineConfig({
-  integrations: [stalux({
-    components: {
-      Navs: "./src/components/CustomNavs.astro",
-      Footer: "./src/components/CustomFooter.astro",
-      // ... see full list in src/internal/override.ts
-    }
-  })],
+    integrations: [
+        stalux({
+            components: {
+                Navs: "./src/components/CustomNavs.astro",
+                Footer: "./src/components/CustomFooter.astro",
+                // ... see full list in src/internal/override.ts
+            },
+        }),
+    ],
 });
 ```
 

package/package.json

@@ -1,25 +1,27 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.2.0",
+    "version": "1.3.0",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
-    "type": "module",
-    "license": "MIT",
-    "author": "xingwangzhe",
-    "homepage": "https://stalux.needhelp.icu",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/xingwangzhe/stalux.git"
-    },
-    "bugs": "https://github.com/xingwangzhe/stalux/issues",
     "keywords": [
         "astro",
-        "astro-theme",
         "astro-integration",
+        "astro-theme",
         "blog",
         "blog-theme",
         "stalux",
         "static-site"
     ],
+    "homepage": "https://stalux.needhelp.icu",
+    "bugs": "https://github.com/xingwangzhe/stalux/issues",
+    "license": "MIT",
+    "author": "xingwangzhe",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/xingwangzhe/stalux.git"
+    },
+    "bin": {
+        "stalux": "scripts/cli.mjs"
+    },
     "files": [
         "src/index.ts",
         "src/config.ts",
@@ -40,6 +42,7 @@
         "template/**/*",
         "!src/content.config.ts"
     ],
+    "type": "module",
     "exports": {
         ".": "./src/index.ts",
         "./config": "./src/config.ts",
@@ -56,12 +59,8 @@
         "./assets/*": "./src/assets/*",
         "./package.json": "./package.json"
     },
-    "bin": {
-        "stalux": "scripts/cli.mjs"
-    },
     "scripts": {
         "dev": "astro dev ",
-        "prebuild": "bun run scripts/font-subset.ts",
         "build": "astro build ",
         "preview": "astro preview ",
         "astro": "astro",
@@ -80,10 +79,8 @@
         "animejs": "^4.5.0",
         "astro": "^7.1.3",
         "pagefind": "^1.5.2",
-        "photoswipe": "^5.4.4"
-    },
-    "peerDependencies": {
-        "astro": "^7.0.0"
+        "photoswipe": "^5.4.4",
+        "subset-font": "^2.5.0"
     },
     "devDependencies": {
         "@astrojs/rss": "^4.0.19",
@@ -101,8 +98,10 @@
         "oxfmt": "^0.60.0",
         "oxlint": "^1.75.0",
         "simple-icons": "^16.27.1",
-        "subset-font": "^2.5.0",
         "temml": "^0.13.3",
         "typescript": "^7.0.2"
+    },
+    "peerDependencies": {
+        "astro": "^7.0.0"
     }
 }

package/scripts/cli.mjs

@@ -18,27 +18,27 @@ const PACKAGE_ROOT = resolve(__dirname, "..");
 const TEMPLATE_DIR = join(PACKAGE_ROOT, "template");
 
 function copyDir(src, dest, overwrite = false) {
-  mkdirSync(dest, { recursive: true });
-  for (const entry of readdirSync(src)) {
-    const srcPath = join(src, entry);
-    const destPath = join(dest, entry);
-    if (entry === "node_modules") continue;
-
-    if (statSync(srcPath).isDirectory()) {
-      copyDir(srcPath, destPath, overwrite);
-    } else {
-      if (!overwrite && existsSync(destPath)) {
-        console.log(`  ⏭  ${entry} (already exists, skipped)`);
-        continue;
-      }
-      cpSync(srcPath, destPath);
-      console.log(`  ✅  ${entry}`);
+    mkdirSync(dest, { recursive: true });
+    for (const entry of readdirSync(src)) {
+        const srcPath = join(src, entry);
+        const destPath = join(dest, entry);
+        if (entry === "node_modules") continue;
+
+        if (statSync(srcPath).isDirectory()) {
+            copyDir(srcPath, destPath, overwrite);
+        } else {
+            if (!overwrite && existsSync(destPath)) {
+                console.log(`  ⏭  ${entry} (already exists, skipped)`);
+                continue;
+            }
+            cpSync(srcPath, destPath);
+            console.log(`  ✅  ${entry}`);
+        }
     }
-  }
 }
 
 function printHelp() {
-  console.log(`
+    console.log(`
   Stalux — Modern Astro Blog Theme
 
   Usage:
@@ -56,17 +56,17 @@ function printHelp() {
 }
 
 function printNextSteps(targetDir) {
-  console.log("");
-  console.log("  📝  Next Steps:");
-  console.log("");
-  console.log(`    1. cd ${targetDir}`);
-  console.log(`    2. npm install stalux`);
-  console.log(`    3. Edit astro.config.mjs to add stalux()`);
-  console.log(`    4. Start writing content in ${targetDir}/stalux/posts/`);
-  console.log(`    5. npm run dev`);
-  console.log("");
-  console.log("  📖  Docs: https://stalux.needhelp.icu");
-  console.log("");
+    console.log("");
+    console.log("  📝  Next Steps:");
+    console.log("");
+    console.log(`    1. cd ${targetDir}`);
+    console.log(`    2. npm install stalux`);
+    console.log(`    3. Edit astro.config.mjs to add stalux()`);
+    console.log(`    4. Start writing content in ${targetDir}/stalux/posts/`);
+    console.log(`    5. npm run dev`);
+    console.log("");
+    console.log("  📖  Docs: https://stalux.needhelp.icu");
+    console.log("");
 }
 
 // ---- Main ----
@@ -74,27 +74,29 @@ const args = process.argv.slice(2);
 const command = args[0];
 
 if (!command || command === "--help" || command === "-h") {
-  printHelp();
-  process.exit(0);
+    printHelp();
+    process.exit(0);
 }
 
 if (command === "init") {
-  const targetArg = args[1] || ".";
-  const targetPath = resolve(process.cwd(), targetArg);
-
-  if (!existsSync(TEMPLATE_DIR)) {
-    console.error("❌ Template directory not found. Ensure stalux package is properly installed.");
-    process.exit(1);
-  }
+    const targetArg = args[1] || ".";
+    const targetPath = resolve(process.cwd(), targetArg);
+
+    if (!existsSync(TEMPLATE_DIR)) {
+        console.error(
+            "❌ Template directory not found. Ensure stalux package is properly installed.",
+        );
+        process.exit(1);
+    }
 
-  console.log(`📦 Initializing Stalux content template...`);
-  console.log(`📂 Target: ${targetPath}`);
-  console.log("");
+    console.log(`📦 Initializing Stalux content template...`);
+    console.log(`📂 Target: ${targetPath}`);
+    console.log("");
 
-  copyDir(TEMPLATE_DIR, targetPath, false);
+    copyDir(TEMPLATE_DIR, targetPath, false);
 
-  printNextSteps(targetArg);
-  process.exit(0);
+    printNextSteps(targetArg);
+    process.exit(0);
 }
 
 // Unknown command

package/src/components/stalux/layout/listPage.astro

@@ -10,14 +10,15 @@ interface Props {
     description: string;
     heading: string;
     subheading?: string;
+    fontSubsetId?: string;
 }
 
-const { title, description, heading, subheading } = Astro.props;
+const { title, description, heading, subheading, fontSubsetId } = Astro.props;
 const configEntries = await getCollection("config");
 const siteConfig = getSiteData(configEntries);
 ---
 
-<Stalux title={title + " | " + siteConfig.title} description={description}>
+<Stalux title={title + " | " + siteConfig.title} description={description} fontSubsetId={fontSubsetId}>
     <div style="height: 3em;"></div>
     <Navs />
     <h1 class={styles.title}>{heading}</h1>

package/src/config.ts

@@ -11,48 +11,48 @@ export type ComponentOverrideMap = Partial<Record<StaluxComponentKey, string>>;
 
 /** 内容集合路径配置 */
 export interface ContentPaths {
-  /** 内容根目录，默认为 "stalux" */
-  root?: string;
-  /** 文章目录，相对于 root */
-  posts?: string;
-  /** 配置目录，相对于 root */
-  config?: string;
-  /** 关于页面目录，相对于 root */
-  about?: string;
-  /** 随想目录，相对于 root */
-  words?: string;
+    /** 内容根目录，默认为 "stalux" */
+    root?: string;
+    /** 文章目录，相对于 root */
+    posts?: string;
+    /** 配置目录，相对于 root */
+    config?: string;
+    /** 关于页面目录，相对于 root */
+    about?: string;
+    /** 随想目录，相对于 root */
+    words?: string;
 }
 
 /** Analytics 配置 */
 export interface AnalyticsConfig {
-  googleAnalyticsId?: string;
-  bingClarityId?: string;
-  umami?: {
-    id: string;
-    url: string;
-  };
+    googleAnalyticsId?: string;
+    bingClarityId?: string;
+    umami?: {
+        id: string;
+        url: string;
+    };
 }
 
 /** Stalux 集成选项 */
 export interface StaluxOptions {
-  /** 内容目录路径（默认 "stalux"） */
-  contentDir?: string;
+    /** 内容目录路径（默认 "stalux"） */
+    contentDir?: string;
 
-  /** 内容子目录路径覆盖 */
-  contentPaths?: ContentPaths;
+    /** 内容子目录路径覆盖 */
+    contentPaths?: ContentPaths;
 
-  /** 组件覆盖映射 */
-  components?: ComponentOverrideMap;
+    /** 组件覆盖映射 */
+    components?: ComponentOverrideMap;
 
-  /** Analytics 配置 */
-  analytics?: AnalyticsConfig;
+    /** Analytics 配置 */
+    analytics?: AnalyticsConfig;
 
-  /** 构建后是否自动运行 Pagefind 索引（默认 true） */
-  pagefind?: boolean;
+    /** 构建后是否自动运行 Pagefind 索引（默认 true） */
+    pagefind?: boolean;
 
-  /** 开发工具栏应用（默认 true） */
-  devToolbar?: boolean;
+    /** 开发工具栏应用（默认 true） */
+    devToolbar?: boolean;
 
-  /** 站点 URL（默认从 astro.config 读取） */
-  site?: string;
+    /** 站点 URL（默认从 astro.config 读取） */
+    site?: string;
 }