@x-withu/page-withu 0.1.0 → 0.1.2

package/bin/page-withu.js

@@ -16,6 +16,17 @@ const templateDir = path.resolve(__dirname, '../template');
 const manifestName = '.page-withu.json';
 const managedRoots = ['src'];
 const managedFiles = ['index.html', 'vite.config.js'];
+const generatedGitignore = `node_modules/
+dist/
+
+.env
+.env.*
+!.env.example
+*.local
+
+.DS_Store
+.idea/
+`;
 
 const program = new Command();
 
@@ -48,7 +59,11 @@ async function listFiles(dir) {
 }
 
 async function listManagedTemplateFiles() {
-    const files = [...managedFiles];
+    const files = [];
+
+    for (const file of managedFiles) {
+        if (await fs.pathExists(path.join(templateDir, file))) files.push(file);
+    }
 
     for (const root of managedRoots) {
         const rootPath = path.join(templateDir, root);
@@ -126,6 +141,19 @@ async function loadManifest(projectDir) {
     return fs.readJson(manifestPath);
 }
 
+async function ensureGeneratedGitignore(projectDir, dryRun) {
+    const gitignorePath = path.join(projectDir, '.gitignore');
+    const npmignorePath = path.join(projectDir, '.npmignore');
+    const hasGitignore = await fs.pathExists(gitignorePath);
+    const hasNpmignore = await fs.pathExists(npmignorePath);
+
+    if (dryRun) return !hasGitignore || hasNpmignore;
+    if (hasNpmignore) await fs.remove(npmignorePath);
+    if (!hasGitignore) await fs.writeFile(gitignorePath, generatedGitignore);
+
+    return !hasGitignore || hasNpmignore;
+}
+
 async function shouldOverwriteConflict(file, options) {
     if (options.force) return true;
     if (options.yes || options.dryRun) return false;
@@ -222,14 +250,15 @@ function printUpdateSummary(summary, dryRun) {
     if (summary.added.length) console.log(chalk.green(`${label} ${summary.added.length} missing file(s).`));
     if (summary.updated.length) console.log(chalk.green(`${label} ${summary.updated.length} template file(s).`));
     if (summary.packageChanged) console.log(chalk.green(`${label} package.json dependencies and scripts.`));
+    if (summary.gitignoreChanged) console.log(chalk.green(`${label} .gitignore.`));
     if (summary.skipped.length) {
         console.log(chalk.yellow(`Skipped ${summary.skipped.length} file(s) with local changes:`));
         for (const file of summary.skipped) console.log(chalk.yellow(`  - ${file}`));
     }
-    if (!summary.added.length && !summary.updated.length && !summary.packageChanged && !summary.skipped.length) {
+    if (!summary.added.length && !summary.updated.length && !summary.packageChanged && !summary.gitignoreChanged && !summary.skipped.length) {
         console.log(chalk.green('Page With U project is already up to date.'));
     }
-    if (!dryRun && (summary.added.length || summary.updated.length || summary.packageChanged)) {
+    if (!dryRun && (summary.added.length || summary.updated.length || summary.packageChanged || summary.gitignoreChanged)) {
         console.log(chalk.cyan('\nNext steps:'));
         console.log(chalk.cyan('  npm install'));
         console.log(chalk.cyan('  npm run build'));
@@ -329,6 +358,7 @@ program
             await fs.writeJson(pkgPath, projectPkg, { spaces: 2 });
 
             await fs.ensureDir(path.join(fullPath, 'content/blog'));
+            await ensureGeneratedGitignore(fullPath, false);
             await writeManifest(fullPath, false);
 
             spinner.succeed(chalk.green(`Successfully created PageWithU project in ${targetDir}!`));
@@ -366,10 +396,11 @@ program
             const previousManifest = await loadManifest(projectDir);
             const updates = await planTemplateUpdates(projectDir, options);
             const packageChanged = await mergePackage(projectDir, options.dryRun);
+            const gitignoreChanged = await ensureGeneratedGitignore(projectDir, options.dryRun);
 
             if (!options.dryRun) await writeManifest(projectDir, false, previousManifest);
 
-            printUpdateSummary({ ...updates, packageChanged }, options.dryRun);
+            printUpdateSummary({ ...updates, packageChanged, gitignoreChanged }, options.dryRun);
         } catch (err) {
             spinner.fail(chalk.red('Failed to update project.'));
             console.error(err);

package/docs/deploy.md

@@ -38,19 +38,60 @@ npm run preview
 
 ## 部署到 GitHub Pages
 
-本仓库已经内置 GitHub Pages 自动部署流程：
+GitHub Pages 适合把你生成好的个人主页托管到 GitHub 仓库中。
+
+### 方式一：使用 GitHub Actions 自动部署
+
+在你自己的主页项目中创建部署工作流：
 
 ```text
 .github/workflows/deploy-pages.yml
 ```
 
-它会在推送到 `main` 分支时自动执行：
-
-1. 进入 `template/`。
-2. 执行 `npm ci` 安装模板依赖。
-3. 使用 `BASE_PATH=/page-withu/ npm run build` 构建模板。
-4. 上传 `template/dist/`。
-5. 发布到 GitHub Pages。
+示例内容：
+
+```yaml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
+```
 
 首次使用前，需要在 GitHub 仓库中打开：
 
@@ -58,24 +99,23 @@ npm run preview
 Settings → Pages → Build and deployment → Source → GitHub Actions
 ```
 
-配置完成后，每次推送到 `main` 分支都会自动更新：
+配置完成后，每次推送到 `main` 分支都会自动构建并发布你的站点。
 
-```text
-https://explorer-dong.github.io/page-withu/
-```
+如果仓库名不是用于根域名的 `用户名.github.io`，通常需要给构建命令设置子路径。例如仓库名是 `my-homepage`：
 
-如果想手动触发部署，也可以在 GitHub Actions 页面选择 `Deploy Template to GitHub Pages`，然后点击 `Run workflow`。
+```yaml
+- run: BASE_PATH=/my-homepage/ npm run build
+```
 
-### 手动上传 dist
+### 方式二：手动上传 dist
 
 如果不想使用 GitHub Actions，也可以本地构建后手动上传 `dist/`。
 
 ```bash
-cd template
-BASE_PATH=/page-withu/ npm run build
+npm run build
 ```
 
-然后把 `template/dist/` 内容上传到用于 GitHub Pages 的发布分支或目录。
+然后把 `dist/` 内容上传到用于 GitHub Pages 的发布分支或目录。
 
 ## 部署到 Cloudflare Pages
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x-withu/page-withu",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A lightweight, elegant personal homepage generator.",
   "repository": {
     "type": "git",