@x-withu/page-withu 0.1.2 → 1.0.0

package/README.md

@@ -41,18 +41,18 @@
 # 安装 page-withu
 npm install -g @x-withu/page-withu
 
-# 创建项目（会依次询问站点标题、作者名、标签页标题、favicon、GitHub 链接和邮箱）
-page-withu create my-homepage
-
-# 也可以通过参数直接指定
-page-withu create my-homepage --title "My Site" --tab-title "My Blog" --favicon /favicon.svg
+# 创建项目，默认配置会写入 config.js，后续可自行编辑
+page-withu new my-homepage
 
 # 安装依赖
 cd my-homepage
 npm install
 
-# 预览网站
-npm run dev
+# 本地预览
+page-withu serve
+
+# 构建分发产物
+page-withu build
 ```
 
 下一步？[配置网站](./docs/setup.md)、[部署网站](./docs/deploy.md)、[开发网站](./docs/develop.md)。

package/bin/page-withu.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
-import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
 import { Command } from 'commander';
-import inquirer from 'inquirer';
 import fs from 'fs-extra';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -13,117 +12,8 @@ const pkg = await fs.readJson(new URL('../package.json', import.meta.url));
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 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();
 
-function hashContent(content) {
-    return createHash('sha256').update(content).digest('hex');
-}
-
-async function hashFile(filePath) {
-    return hashContent(await fs.readFile(filePath));
-}
-
-function toPosixPath(value) {
-    return value.split(path.sep).join('/');
-}
-
-async function listFiles(dir) {
-    const entries = await fs.readdir(dir, { withFileTypes: true });
-    const files = [];
-
-    for (const entry of entries) {
-        const entryPath = path.join(dir, entry.name);
-        if (entry.isDirectory()) {
-            files.push(...await listFiles(entryPath));
-        } else if (entry.isFile()) {
-            files.push(entryPath);
-        }
-    }
-
-    return files;
-}
-
-async function listManagedTemplateFiles() {
-    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);
-        if (!await fs.pathExists(rootPath)) continue;
-        const rootFiles = await listFiles(rootPath);
-        files.push(...rootFiles.map((file) => toPosixPath(path.relative(templateDir, file))));
-    }
-
-    return files.sort((a, b) => a.localeCompare(b));
-}
-
-async function createManifest(projectDir, previousManifest = null) {
-    const files = {};
-
-    for (const file of await listManagedTemplateFiles()) {
-        const projectFile = path.join(projectDir, file);
-        const templateFile = path.join(templateDir, file);
-        if (!await fs.pathExists(projectFile)) continue;
-
-        const projectHash = await hashFile(projectFile);
-        const templateHash = await hashFile(templateFile);
-        if (projectHash === templateHash) {
-            files[file] = templateHash;
-        } else if (previousManifest?.files?.[file]) {
-            files[file] = previousManifest.files[file];
-        }
-    }
-
-    return {
-        templateVersion: pkg.version,
-        updatedAt: new Date().toISOString(),
-        files,
-    };
-}
-
-async function writeManifest(projectDir, dryRun, previousManifest = null) {
-    const manifest = await createManifest(projectDir, previousManifest);
-    if (!dryRun) {
-        await fs.writeJson(path.join(projectDir, manifestName), manifest, { spaces: 2 });
-    }
-    return manifest;
-}
-
-function renderConfig({ title, tabTitle, favicon, author, footerLinks }) {
-    const links = footerLinks.map((link) => `        { label: ${JSON.stringify(link.label)}, url: ${JSON.stringify(link.url)} }`);
-    return `export default {
-    title: ${JSON.stringify(title)},
-    tabTitle: ${JSON.stringify(tabTitle)},
-    favicon: ${JSON.stringify(favicon)},
-    author: ${JSON.stringify(author)},
-    year: new Date().getFullYear(),
-    footerLinks: [
-${links.join(',\n')}
-    ],
-    pagination: {
-        pageSize: 5
-    }
-}`;
-}
-
 async function detectProject(projectDir) {
     const required = ['package.json', 'config.js', 'content', 'src', 'vite.config.js'];
     const missing = [];
@@ -135,277 +25,91 @@ async function detectProject(projectDir) {
     return missing;
 }
 
-async function loadManifest(projectDir) {
-    const manifestPath = path.join(projectDir, manifestName);
-    if (!await fs.pathExists(manifestPath)) return null;
-    return fs.readJson(manifestPath);
+function shouldCopyTemplateItem(source) {
+    return path.relative(templateDir, source) !== '.gitignore';
 }
 
-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;
+function normalizePackageName(name) {
+    return name.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/^-+|-+$/g, '') || 'page-withu-site';
 }
 
-async function shouldOverwriteConflict(file, options) {
-    if (options.force) return true;
-    if (options.yes || options.dryRun) return false;
-
-    const answer = await inquirer.prompt([{
-        type: 'confirm',
-        name: 'overwrite',
-        message: `${file} has local changes. Overwrite it?`,
-        default: false,
-    }]);
-
-    return answer.overwrite;
-}
+async function createProject(projectName = 'my-homepage') {
+    const targetDir = projectName.trim() || 'my-homepage';
+    const fullPath = path.resolve(process.cwd(), targetDir);
 
-async function planTemplateUpdates(projectDir, options) {
-    const manifest = await loadManifest(projectDir);
-    const files = await listManagedTemplateFiles();
-    const result = {
-        added: [],
-        updated: [],
-        skipped: [],
-        unchanged: [],
-    };
-
-    for (const file of files) {
-        const sourceFile = path.join(templateDir, file);
-        const targetFile = path.join(projectDir, file);
-        const sourceHash = await hashFile(sourceFile);
-        const exists = await fs.pathExists(targetFile);
-
-        if (!exists) {
-            result.added.push(file);
-            if (!options.dryRun) await fs.copy(sourceFile, targetFile);
-            continue;
-        }
-
-        const currentHash = await hashFile(targetFile);
-        if (currentHash === sourceHash) {
-            result.unchanged.push(file);
-            continue;
-        }
+    if (await fs.pathExists(fullPath)) {
+        console.error(chalk.red(`\nError: Directory ${targetDir} already exists.`));
+        process.exit(1);
+    }
 
-        const previousHash = manifest?.files?.[file];
-        const safeToUpdate = previousHash && currentHash === previousHash;
-        const overwrite = safeToUpdate || await shouldOverwriteConflict(file, options);
+    const spinner = ora('Creating project...').start();
 
-        if (overwrite) {
-            result.updated.push(file);
-            if (!options.dryRun) await fs.copy(sourceFile, targetFile);
-        } else {
-            result.skipped.push(file);
-        }
-    }
+    try {
+        await fs.copy(templateDir, fullPath, { filter: shouldCopyTemplateItem });
 
-    return result;
-}
+        const pkgPath = path.join(fullPath, 'package.json');
+        const projectPkg = await fs.readJson(pkgPath);
+        projectPkg.name = normalizePackageName(path.basename(targetDir));
+        await fs.writeJson(pkgPath, projectPkg, { spaces: 2 });
 
-function mergeSection(projectPkg, templatePkg, key) {
-    const next = { ...(projectPkg[key] || {}) };
-    let changed = false;
+        await fs.ensureDir(path.join(fullPath, 'content/blog'));
 
-    for (const [name, value] of Object.entries(templatePkg[key] || {})) {
-        if (next[name] !== value) {
-            next[name] = value;
-            changed = true;
-        }
+        spinner.succeed(chalk.green(`Successfully created PageWithU project in ${targetDir}!`));
+        console.log('\nNext steps:');
+        console.log(chalk.cyan(`  cd ${targetDir}`));
+        console.log(chalk.cyan('  npm install'));
+        console.log(chalk.cyan('  page-withu serve'));
+        console.log(chalk.cyan('  page-withu build\n'));
+    } catch (err) {
+        spinner.fail(chalk.red('Failed to create project.'));
+        console.error(err);
+        process.exit(1);
     }
-
-    if (changed) projectPkg[key] = next;
-    return changed;
 }
 
-async function mergePackage(projectDir, dryRun) {
-    const projectPkgPath = path.join(projectDir, 'package.json');
-    const templatePkg = await fs.readJson(path.join(templateDir, 'package.json'));
-    const projectPkg = await fs.readJson(projectPkgPath);
-    const before = JSON.stringify(projectPkg);
-
-    mergeSection(projectPkg, templatePkg, 'scripts');
-    mergeSection(projectPkg, templatePkg, 'dependencies');
-    mergeSection(projectPkg, templatePkg, 'devDependencies');
-
-    const changed = JSON.stringify(projectPkg) !== before;
-    if (changed && !dryRun) {
-        await fs.writeJson(projectPkgPath, projectPkg, { spaces: 2 });
+async function runProjectScript(script, args) {
+    const missing = await detectProject(process.cwd());
+    if (missing.length) {
+        console.error(chalk.red('Current directory does not look like a PageWithU project.'));
+        console.error(chalk.yellow(`Missing: ${missing.join(', ')}`));
+        process.exit(1);
     }
 
-    return changed;
-}
-
-function printUpdateSummary(summary, dryRun) {
-    const label = dryRun ? 'Would update' : 'Updated';
+    const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const child = spawn(npmCommand, ['run', script, '--', ...args], {
+        cwd: process.cwd(),
+        stdio: 'inherit',
+    });
 
-    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.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 || summary.gitignoreChanged)) {
-        console.log(chalk.cyan('\nNext steps:'));
-        console.log(chalk.cyan('  npm install'));
-        console.log(chalk.cyan('  npm run build'));
-    }
+    child.on('exit', (code, signal) => {
+        if (signal) {
+            process.kill(process.pid, signal);
+            return;
+        }
+        process.exit(code ?? 1);
+    });
 }
 
 program
     .name('page-withu')
-    .description('CLI to scaffold a lightweight, elegant personal homepage')
+    .description('CLI to scaffold, preview, and build a lightweight personal homepage')
     .version(pkg.version);
 
 program
-    .command('create [project-name]')
-    .description('create a new PageWithU project')
-    .option('-t, --title <title>', 'site title')
-    .option('--tab-title <title>', 'browser tab title')
-    .option('--favicon <path-or-url>', 'browser tab favicon path or URL')
-    .option('-a, --author <author>', 'author name')
-    .option('-g, --github <github>', 'github url')
-    .option('-e, --email <email>', 'email address')
-    .action(async (projectName, options) => {
-        let targetDir = projectName;
-
-        if (!targetDir) {
-            const answers = await inquirer.prompt([
-                {
-                    type: 'input',
-                    name: 'projectName',
-                    message: 'What is your project named?',
-                    default: 'my-homepage',
-                },
-            ]);
-            targetDir = answers.projectName;
-        }
-
-        const fullPath = path.resolve(process.cwd(), targetDir);
-
-        if (fs.existsSync(fullPath)) {
-            console.error(chalk.red(`\nError: Directory ${targetDir} already exists.`));
-            process.exit(1);
-        }
-
-        const title = options.title || (await inquirer.prompt([{
-            type: 'input',
-            name: 'title',
-            message: 'Site Title:',
-            default: 'PageWithU',
-        }])).title;
-
-        const author = options.author || (await inquirer.prompt([{
-            type: 'input',
-            name: 'author',
-            message: 'Author Name:',
-            default: 'Your Name',
-        }])).author;
-
-        const tabTitle = options.tabTitle || (await inquirer.prompt([{
-            type: 'input',
-            name: 'tabTitle',
-            message: 'Browser Tab Title:',
-            default: title,
-        }])).tabTitle;
-
-        const favicon = options.favicon || (await inquirer.prompt([{
-            type: 'input',
-            name: 'favicon',
-            message: 'Favicon path or URL:',
-            default: '/src/assets/bulb.svg',
-        }])).favicon;
-
-        const github = options.github !== undefined ? options.github : (await inquirer.prompt([{
-            type: 'input',
-            name: 'github',
-            message: 'GitHub URL (optional):',
-        }])).github;
-
-        const email = options.email !== undefined ? options.email : (await inquirer.prompt([{
-            type: 'input',
-            name: 'email',
-            message: 'Email (optional):',
-        }])).email;
-
-        const spinner = ora('Creating project...').start();
-
-        try {
-            await fs.copy(templateDir, fullPath);
-
-            const footerLinks = [];
-            if (github) footerLinks.push({ label: 'GitHub', url: github });
-            if (email) footerLinks.push({ label: 'Email', url: `mailto:${email}` });
-
-            await fs.writeFile(path.join(fullPath, 'config.js'), renderConfig({ title, tabTitle, favicon, author, footerLinks }));
-
-            const pkgPath = path.join(fullPath, 'package.json');
-            const projectPkg = await fs.readJson(pkgPath);
-            projectPkg.name = targetDir.toLowerCase().replace(/[^a-z0-9-]/g, '-');
-            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}!`));
-            console.log('\nNext steps:');
-            console.log(chalk.cyan(`  cd ${targetDir}`));
-            console.log(chalk.cyan('  npm install'));
-            console.log(chalk.cyan('  npm run dev\n'));
-
-        } catch (err) {
-            spinner.fail(chalk.red('Failed to create project.'));
-            console.error(err);
-            process.exit(1);
-        }
-    });
+    .command('new [project-name]')
+    .description('create a new PageWithU project with the default template config')
+    .action(createProject);
 
 program
-    .command('update')
-    .description('update an existing PageWithU project with the latest template')
-    .option('--dry-run', 'show what would change without writing files')
-    .option('--yes', 'skip prompts and apply safe updates')
-    .option('--force', 'overwrite changed template-managed files')
-    .action(async (options) => {
-        const projectDir = process.cwd();
-        const spinner = ora(options.dryRun ? 'Checking project update...' : 'Updating project...').start();
-
-        try {
-            const missing = await detectProject(projectDir);
-            if (missing.length) {
-                spinner.fail(chalk.red('Current directory does not look like a PageWithU project.'));
-                console.error(chalk.yellow(`Missing: ${missing.join(', ')}`));
-                process.exit(1);
-            }
+    .command('serve [args...]')
+    .description('start local preview for the current PageWithU project')
+    .allowUnknownOption(true)
+    .action((args = []) => runProjectScript('dev', args));
 
-            spinner.stop();
-            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, gitignoreChanged }, options.dryRun);
-        } catch (err) {
-            spinner.fail(chalk.red('Failed to update project.'));
-            console.error(err);
-            process.exit(1);
-        }
-    });
+program
+    .command('build [args...]')
+    .description('build dist assets for the current PageWithU project')
+    .allowUnknownOption(true)
+    .action((args = []) => runProjectScript('build', args));
 
 program.parse();

package/docs/develop.md

@@ -46,18 +46,18 @@ bin/page-withu.js
 
 当前 CLI 主要负责：
 
-1. 读取命令行参数或交互式输入。
-2. 复制 `template/` 到目标目录。
-3. 根据用户输入生成目标项目的 `config.js`。
-4. 修改目标项目 `package.json` 的 `name` 字段。
-5. 输出下一步命令提示。
+1. `new`：复制 `template/` 到目标目录，保留默认配置。
+2. `serve`：在当前主页项目中启动本地预览。
+3. `build`：在当前主页项目中构建 `dist` 产物。
 
 本地调试 CLI：
 
 ```bash
 node bin/page-withu.js --help
-node bin/page-withu.js create my-homepage
-node bin/page-withu.js update --dry-run
+node bin/page-withu.js new my-homepage
+cd my-homepage
+node /path/to/page-withu/bin/page-withu.js serve
+node /path/to/page-withu/bin/page-withu.js build
 ```
 
 如果想全局挂载本地版本：
@@ -65,14 +65,12 @@ node bin/page-withu.js update --dry-run
 ```bash
 npm link
 page-withu --help
-page-withu create my-homepage
+page-withu new my-homepage
 ```
 
-新增 CLI 参数时，通常需要同步修改：
+调整 CLI 行为时，通常需要同步修改：
 
-- `bin/page-withu.js` 中的 commander option。
-- 交互式 prompt 的默认值。
-- 生成 `config.js` 的逻辑。
+- `bin/page-withu.js` 中的 commander command。
 - 必要时修改 `template/config.js` 的默认字段。
 - 必要时修改模板中读取配置的 Vue 组件。
 - 必要时更新 `README.md` 和 `docs/setup.md`。
@@ -82,13 +80,13 @@ page-withu create my-homepage
 ```bash
 mkdir -p /tmp/page-withu-test
 cd /tmp/page-withu-test
-node /path/to/page-withu/bin/page-withu.js create demo-site --title "Demo" --author "Tester"
+node /path/to/page-withu/bin/page-withu.js new demo-site
 cd demo-site
 npm install
-npm run build
+node /path/to/page-withu/bin/page-withu.js build
 ```
 
-如果 `npm run build` 成功，说明模板可以被正常生成和构建。
+如果构建成功，说明模板可以被正常生成和构建。
 
 ## 开发 Template
 
@@ -202,11 +200,11 @@ npm publish --access public
 
 ```bash
 npm install -g @x-withu/page-withu
-page-withu create my-homepage
+page-withu new my-homepage
 ```
 
 或在线构建无需本地安装：
 
 ```bash
-npx @x-withu/page-withu create my-homepage
+npx @x-withu/page-withu new my-homepage
 ```

package/docs/setup.md

@@ -83,36 +83,21 @@ index_img: https://example.com/cover.jpg
 - `tags`：文章标签。
 - `index_img`：博客列表封面图，可选；不填会保留占位布局。
 
-## 更新项目
+## CLI 命令
 
-如果你已经用 `page-withu create` 创建过项目，后续升级 CLI 后可以在项目目录中更新模板能力：
+Page With U 只提供三个常用命令：
 
 ```bash
-npm install -g @x-withu/page-withu
-cd my-homepage
-page-withu update --dry-run
-page-withu update
+page-withu new my-homepage
+page-withu serve
+page-withu build
 ```
 
-`page-withu update` 会更新模板管理的文件，例如 `src/`、`index.html` 和 `vite.config.js`，并合并 `package.json` 中模板需要的脚本和依赖。
+- `page-withu new my-homepage`：新建主页项目，所有站点配置都保持模板默认值。
+- `page-withu serve`：在当前项目目录启动本地预览，对应模板项目的 `npm run dev`。
+- `page-withu build`：在当前项目目录构建 `dist` 产物，对应模板项目的 `npm run build`。
 
-为了避免覆盖你的内容，以下文件默认不会被更新：
-
-- `config.js`
-- `content/`
-
-如果你修改过模板源码，更新时会跳过有冲突的文件并在终端列出来。确认要覆盖这些模板源码时，可以使用：
-
-```bash
-page-withu update --force
-```
-
-更新完成后建议执行：
-
-```bash
-npm install
-npm run build
-```
+创建完成后，直接编辑 `config.js`、`content/index.md`、`content/domains.md` 和 `content/blog/` 即可定制网站。
 
 ## Markdown
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x-withu/page-withu",
-  "version": "0.1.2",
+  "version": "1.0.0",
   "description": "A lightweight, elegant personal homepage generator.",
   "repository": {
     "type": "git",
@@ -37,7 +37,6 @@
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "fs-extra": "^11.2.0",
-    "inquirer": "^9.3.2",
     "ora": "^8.0.1"
   }
 }

package/template/src/components/blog-detail.vue

@@ -24,10 +24,19 @@
                 </nav>
             </div>
 
-            <aside v-if="toc.length" class="blog-toc" aria-label="Table of contents">
-                <p>Contents</p>
+            <button v-if="toc.length" class="blog-toc-toggle" type="button" :aria-expanded="tocOpen"
+                aria-controls="blog-toc" @click="tocOpen = true">
+                目录
+            </button>
+            <div v-if="toc.length && tocOpen" class="blog-toc-backdrop" @click="tocOpen = false"></div>
+            <aside v-if="toc.length" id="blog-toc" :class="['blog-toc', { open: tocOpen }]" aria-label="Table of contents">
+                <div class="blog-toc-header">
+                    <p>目录</p>
+                    <button class="blog-toc-close" type="button" aria-label="Close table of contents"
+                        @click="tocOpen = false">×</button>
+                </div>
                 <a v-for="item in toc" :key="item.id" :href="`#${item.id}`"
-                    :class="[`toc-level-${item.level}`, { active: activeHeading === item.id }]">
+                    :class="[`toc-level-${item.level}`, { active: activeHeading === item.id }]" @click="tocOpen = false">
                     {{ item.title }}
                 </a>
             </aside>
@@ -58,6 +67,7 @@ defineEmits(['back', 'open-post'])
 const contentRef = ref(null)
 const zoomImage = ref(null)
 const activeHeading = ref('')
+const tocOpen = ref(false)
 const basePath = import.meta.env.BASE_URL.replace(/\/$/, '')
 const blogHref = `${basePath}/blog.html` || '/blog.html'
 let mermaidModule
@@ -118,6 +128,7 @@ onMounted(() => {
 onUnmounted(() => window.removeEventListener('scroll', updateActiveHeading))
 
 watch(() => props.post.slug, () => {
+    tocOpen.value = false
     activeHeading.value = props.toc[0]?.id || ''
     nextTick(() => {
         updateActiveHeading()

package/template/src/styles/main.css

@@ -992,6 +992,14 @@ footer p {
     margin-bottom: 8px;
 }
 
+.blog-toc-toggle {
+    display: none;
+}
+
+.blog-toc-backdrop {
+    display: none;
+}
+
 .blog-toc {
     position: sticky;
     top: 24px;
@@ -1005,6 +1013,17 @@ footer p {
     font-size: 0.84rem;
 }
 
+.blog-toc-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+}
+
+.blog-toc-close {
+    display: none;
+}
+
 .blog-toc p {
     margin: 0 0 4px;
     color: var(--color-heading);
@@ -1197,7 +1216,7 @@ footer p {
 }
 
 /* ===== Responsive: Mobile ===== */
-@media (max-width: 480px) {
+@media (max-width: 960px) {
     body {
         padding: 0 16px;
     }
@@ -1258,10 +1277,80 @@ footer p {
         padding-bottom: 16px;
     }
 
+    .blog-article-layout {
+        grid-template-columns: 1fr;
+    }
+
+    .blog-toc-toggle {
+        position: fixed;
+        right: 18px;
+        bottom: 18px;
+        z-index: 88;
+        display: inline-flex;
+        align-items: center;
+        gap: 6px;
+        padding: 9px 14px;
+        border: 1px solid var(--color-card-border);
+        border-radius: 999px;
+        color: var(--color-heading);
+        background: var(--color-bg);
+        box-shadow: var(--shadow-card);
+        font: inherit;
+        font-size: 0.84rem;
+        cursor: pointer;
+    }
+
+    .blog-toc-backdrop {
+        position: fixed;
+        inset: 0;
+        z-index: 89;
+        display: block;
+        background: rgba(15, 23, 42, 0.36);
+    }
+
     .blog-toc {
-        position: static;
-        order: -1;
-        padding: 12px 0 12px 14px;
+        position: fixed;
+        top: 50%;
+        left: 50%;
+        z-index: 90;
+        width: min(calc(100vw - 48px), 320px);
+        max-height: min(70vh, 480px);
+        padding: 16px;
+        border: 1px solid var(--color-card-border);
+        border-radius: 16px;
+        background: var(--color-card-bg);
+        box-shadow: var(--shadow-card);
+        transform: translate(-50%, -50%);
+        display: none;
+    }
+
+    .blog-toc.open {
+        display: flex;
+    }
+
+    .blog-toc-header {
+        position: sticky;
+        top: -16px;
+        margin: -16px -16px 4px;
+        padding: 16px;
+        background: var(--color-card-bg);
+        border-bottom: 1px solid var(--color-footer-border);
+    }
+
+    .blog-toc-close {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: 28px;
+        height: 28px;
+        border: 1px solid var(--color-card-border);
+        border-radius: 999px;
+        color: var(--color-subtext);
+        background: var(--color-bg);
+        font: inherit;
+        font-size: 1rem;
+        line-height: 1;
+        cursor: pointer;
     }
 
     .blog-nav {