feat: add detailed instructions for creating and maintaining a blog, including protection for custom content

README.md

@@ -78,6 +78,10 @@ Retypeset is a static blog theme based on the [Astro](https://astro.build/) fram
 
 Retypeset releases [new features](https://github.com/radishzzz/astro-theme-retypeset/issues/18) from time to time. You can refer to the [GitHub Docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) and run `Sync fork` in your repository to sync with the latest branch. Do not click `Discard Changes`, or you will lose your modifications.
 
+For details on how to safely pull upstream changes **while preserving your custom content**, see:
+
+👉 [`scripts/README.md`](./scripts/README.md)
+
 ## Credits
 
 - [Typography](https://github.com/moeyua/astro-theme-typography)

README.zh.md

@@ -74,10 +74,15 @@ Retypeset 是一款基于 [Astro](https://astro.build/) 框架的静态博客主
 
  [![Deploy to Netlify](images/deploy-netlify.svg)](https://app.netlify.com/start) [![Deploy to Vercel](images/deploy-vercel.svg)](https://vercel.com/new)
 
+
 ## 更新
 
 Retypeset 会不定期发布 [新功能](https://github.com/radishzzz/astro-theme-retypeset/issues/18)。你可以参考 [GitHub 文档](https://docs.github.com/zh/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)，在仓库中执行 `Sync fork` 以同步最新分支。不要点击 `Discard Changes`，否则会丢失你的更改。
 
+如需了解如何在**保留自定义内容的同时安全地拉取上游更新**，请参阅：
+
+👉 [`scripts/README.md`](./scripts/README.md) 文件
+
 ## 鸣谢
 
 - [Typography](https://github.com/moeyua/astro-theme-typography)

scripts/README-zh.md

@@ -0,0 +1,65 @@
+## 🚀 基于本仓库创建并维护你自己的博客项目
+
+本仓库为 [Astro](https://astro.build/) + [Retype](https://retype.com/) 构建的高颜值博客模板，支持一键部署和持续更新。以下是创建你自己的博客并与本模板保持同步的标准流程。
+
+### ✅ 第一步：创建你自己的仓库
+
+请**不要 Fork** 本仓库。
+相反，请点击 👉 [Use this template](https://github.com/radishzzz/astro-theme-retypeset) 创建一个新的仓库副本。
+
+> 📌 原因说明：Fork 仓库将强制公开，并可能暴露你的私人配置（例如部署密钥、邮箱、API Token 等），不利于信息保护。
+
+---
+
+### ✏️ 第二步：保护你的自定义内容
+
+你将在 `scripts/git-protect.list` 文件中声明需要保护的内容（如你撰写的文章、配置文件、页面自定义设置等）。
+这些文件在后续执行上游同步时会被自动备份和恢复，确保不会被覆盖。
+
+---
+
+### 🌐 第三步：开发并部署你的博客
+
+* 根据项目目录结构撰写你的内容；
+* 使用平台如 [Vercel](https://vercel.com/)、[Netlify](https://www.netlify.com/) 等部署站点；
+
+---
+
+### 🔄 第四步：同步上游更新并保留本地定制
+
+> 在你首次同步前，需添加上游远程地址（只需执行一次）：
+
+```bash
+git remote add upstream https://github.com/radishzzz/astro-theme-retypeset.git
+```
+
+之后每次同步只需在项目根目录执行以下命令：
+
+#### macOS / Linux / WSL / Git Bash（推荐）：
+
+```bash
+chmod u+x scripts/sync-upstream.sh
+bash scripts/sync-upstream.sh upstream/master /tmp/blog-sync
+```
+
+#### Windows 用户注意：
+
+* **请使用 Git Bash** 执行上述命令；
+* ❌ **不建议使用 cmd.exe 或 PowerShell**，以避免路径兼容与权限问题；
+* 如需使用 Windows 运行脚本，推荐 Git Bash。
+
+---
+
+### 📎 常见问题
+
+* **为什么不通过Github Actions 自动化处理？**
+
+  由于游仓库的活跃，无法保证合并不需要人工介入。
+
+* **为何要保护文件？**
+
+  上游可能会变更主题逻辑、样式或结构。通过 `git-protect.list` 声明关键文件，可在合并更新时避免被覆盖。
+
+* **我修改了主题结构，是否还能同步？**
+
+  可以。但需在同步前手动解决冲突，并确保 `git-protect.list` 保护的路径无误。

scripts/README.md

@@ -0,0 +1,66 @@
+## 🚀 Create and Maintain Your Own Blog Based on This Repository
+
+This repository provides a visually polished blog template built with [Astro](https://astro.build/) and [Retype](https://retype.com/), designed for seamless deployment and long-term maintenance. Follow the steps below to initialize your own blog and keep it in sync with future upstream updates.
+
+---
+
+### ✅ Step 1: Create Your Own Repository
+
+**Do not fork this repository.**
+Instead, click 👉 [Use this template](https://github.com/radishzzz/astro-theme-retypeset) to create a new repository based on this template.
+
+> 📌 **Why not fork?**
+> Forked repositories are publicly visible by default, which may expose sensitive configuration data (e.g., deployment tokens, email addresses, API keys), posing a security risk.
+
+---
+
+### ✏️ Step 2: Safeguard Your Custom Content
+
+Declare the files and directories you want to preserve in the `scripts/git-protect.list` file.
+This includes your posts, configuration files, and site-specific settings. These items will be automatically backed up and restored during synchronization with the upstream repository, ensuring they are never overwritten.
+
+---
+
+### 🌐 Step 3: Develop and Deploy Your Blog
+
+* Structure and write your content according to the project’s directory layout.
+* Deploy the site using platforms such as [Vercel](https://vercel.com/) or [Netlify](https://www.netlify.com/).
+* Continuous deployment via GitHub Actions is supported but optional.
+
+---
+
+### 🔄 Step 4: Sync with Upstream While Preserving Local Customizations
+
+> Before the first synchronization, add the upstream remote (only required once):
+
+```bash
+git remote add upstream https://github.com/radishzzz/astro-theme-retypeset.git
+```
+
+Then, run the sync script from the root directory of your repository:
+
+#### macOS / Linux / WSL / Git Bash (Recommended):
+
+```bash
+chmod u+x scripts/sync-upstream.sh
+bash scripts/sync-upstream.sh upstream/master /tmp/blog-sync
+```
+
+#### For Windows Users:
+
+* ✅ **Use Git Bash** to run the above commands;
+* ❌ **Avoid using cmd.exe or PowerShell**, as they may cause compatibility issues with file paths;
+* For best results, stick with Git Bash even on Windows.
+
+---
+
+### 📎 Frequently Asked Questions
+
+* **Why not automate synchronization with GitHub Actions?**
+  Due to the active nature of this upstream repository, automatic merges are not guaranteed to be conflict-free. Manual review is often required.
+
+* **Why are certain files protected?**
+  Upstream updates may introduce structural or styling changes. Defining protected files in `git-protect.list` ensures your custom content is preserved during synchronization.
+
+* **Can I still sync if I’ve modified the theme structure?**
+  Yes, but you'll need to manually resolve conflicts before syncing. Make sure all critical paths are properly listed in `git-protect.list`.

scripts/git-protect.list

@@ -0,0 +1,4 @@
+.cursor/
+src/config.ts
+src/content/
+src/i18n/ui.ts

scripts/sync-upstream.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# filepath: sync-upstream.sh
+
+# 用法: ./sync-upstream.sh <upstream/branch> <tmp_dir>
+# 示例: ./sync-upstream.sh upstream/main /tmp/astro-protect
+
+set -e
+
+###########################
+# 配置区
+DEBUG=true  # 设置为 true 启用调试输出
+PROTECT_LIST="scripts/git-protect.list" # 保护文件列表路径
+###########################
+
+UPSTREAM_BRANCH="$1"
+TMP_DIR="$2"
+
+# 打印调试信息
+log_debug() {
+  if [[ "$DEBUG" == true ]]; then
+    echo -e "[DEBUG] $*"
+  fi
+}
+
+if [[ -z "$UPSTREAM_BRANCH" || -z "$TMP_DIR" ]]; then
+  echo "用法: $0 <upstream/branch> <tmp_dir>"
+  exit 1
+fi
+
+if [[ ! -f "$PROTECT_LIST" ]]; then
+  echo "未找到 $PROTECT_LIST 文件"
+  exit 1
+fi
+
+log_debug "同步上游分支: $UPSTREAM_BRANCH"
+log_debug "临时目录: $TMP_DIR"
+log_debug "保护列表文件: $PROTECT_LIST"
+
+# 确保复制隐藏文件（如 .env）
+shopt -s dotglob
+
+# 1. 备份需要保护的文件/文件夹
+mkdir -p "$TMP_DIR"
+while IFS= read -r path || [[ -n "$path" ]]; do
+  [[ -z "$path" ]] && continue
+  [[ "${path:0:1}" == "#" ]] && continue
+  if [[ -e "$path" ]]; then
+    log_debug "备份: $path"
+    mkdir -p "$TMP_DIR/$(dirname "$path")"
+    cp -r "$path" "$TMP_DIR/$(dirname "$path")/"
+  else
+    log_debug "跳过不存在的路径: $path"
+  fi
+done < "$PROTECT_LIST"
+
+# 2. 用上游分支内容覆盖本地
+log_debug "获取上游分支 ${UPSTREAM_BRANCH%%/*}"
+git fetch "${UPSTREAM_BRANCH%%/*}"
+
+log_debug "从 $UPSTREAM_BRANCH 覆盖当前目录内容"
+git checkout "$UPSTREAM_BRANCH" -- .
+
+# 3. 恢复保护的文件/文件夹
+while IFS= read -r path || [[ -n "$path" ]]; do
+  [[ -z "$path" ]] && continue
+  [[ "${path:0:1}" == "#" ]] && continue
+  if [[ -e "$TMP_DIR/$path" ]]; then
+    log_debug "恢复: $path"
+    rm -rf "$path"
+    mkdir -p "$(dirname "$path")"
+    cp -r "$TMP_DIR/$path" "$path"
+  else
+    log_debug "未找到备份，跳过: $path"
+  fi
+done < "$PROTECT_LIST"
+
+# 4. 清理临时目录
+log_debug "删除临时目录: $TMP_DIR"
+rm -rf "$TMP_DIR"
+
+echo "✅ 同步完成，已保留保护文件。请检查后 git add/commit/push。"