Auto Page Sync — 仓库内容自动同步到前端页面

将仓库中的 Markdown / JSON 内容自动同步到前端项目，生成对应页面，并通过 GitHub Actions 定时更新，确保 Google SEO 内容新鲜度。

When This Skill Applies

• 当用户说「把仓库的 XX 目录同步到网站」时
• 当用户说「每天自动更新页面内容」时
• 当用户需要把 Markdown 报告、博客文章、Changelog 展示到前端时
• 当用户提到「SEO 内容新鲜度」「定时更新」「自动部署」时
• 当用户需要配置 GitHub Actions 定时同步内容到前端时

核心价值

手动更新网站内容既耗时又容易遗忘。这个 Skill 让你：

• 只管往仓库写 Markdown，前端页面自动生成
• GitHub Actions 定时拉取，零人工干预
• 每次更新自动触发部署，Google 爬虫看到的永远是最新内容
• 支持多种页面形态，一套机制复用所有项目

Instructions

Step 1: 分析内容源

1. 读取用户指定的仓库目录结构
2. 识别内容格式（Markdown、JSON、YAML）
3. 分析内容组织方式（按日期、按分类、单文件）
4. 确定元数据提取规则（标题、日期、标签等）

# 典型的内容源结构
daily-reports/
├── 2026-04-10/
│   ├── morning-report.md
│   └── youtube-report.md
├── 2026-04-11/
│   ├── morning-report.md
│   └── youtube-report.md

# 或者博客结构
blog/
├── 2026-04-10-my-first-post.md
├── 2026-04-11-another-post.md

Step 2: 选择页面模式

根据内容类型选择合适的模式：

模式	适用场景	路由结构	特点
A: 日报型	每日报告、周报	/reports/[date]	日期导航 + Tab 切换
B: 博客型	文章、教程	/blog/[slug]	列表页 + 分类筛选
C: 动态区块型	Landing Page 数据	更新现有页面区块	无新路由
D: Changelog 型	更新日志	/changelog	单页时间线

Step 3: 创建静态数据管道

将内容文件复制到前端项目的 public/data/ 目录，并生成索引文件。

目标目录结构：

public/data/{content-type}/
├── index.json          # 索引文件
├── 2026-04-10/
│   ├── report-a.md
│   └── report-b.md
└── 2026-04-11/
    ├── report-a.md
    └── report-b.md

index.json 标准格式：

{
  "dates": ["2026-04-11", "2026-04-10"],
  "latest": "2026-04-11",
  "items": {
    "2026-04-11": [
      {
        "slug": "unique-identifier",
        "title": "显示标题",
        "icon": "🎮",
        "filename": "source-file.md",
        "description": "可选摘要",
        "tags": ["可选标签"]
      }
    ]
  }
}

Step 4: 生成前端页面

根据目标框架生成页面代码。以下以 Next.js App Router 为例：

必须遵循的原则：

• 读取项目现有的 layout.tsx、globals.css、组件库，匹配设计风格
• 使用项目已安装的依赖（如 react-markdown、remark-gfm）
• 响应式设计，移动端友好
• 支持暗色模式（如果项目已有）

日报型页面结构（模式 A）：

app/reports/page.tsx              # 重定向到最新日期
app/reports/[date]/page.tsx       # 日期详情页
components/report-viewer.tsx      # 内容渲染组件

博客型页面结构（模式 B）：

app/blog/page.tsx                 # 文章列表页
app/blog/[slug]/page.tsx          # 文章详情页
components/blog-card.tsx          # 文章卡片组件

内容渲染组件核心逻辑：

// 使用 react-markdown + remark-gfm 渲染 Markdown
import ReactMarkdown from "react-markdown"
import remarkGfm from "remark-gfm"

<article className="prose prose-neutral dark:prose-invert max-w-none">
  <ReactMarkdown remarkPlugins={[remarkGfm]}>
    {markdownContent}
  </ReactMarkdown>
</article>

Step 5: 添加导航入口

在项目的全局导航中添加新页面链接，使用与现有导航一致的样式。

Step 6: 配置 GitHub Actions 定时同步

创建 .github/workflows/sync_{content_type}.yml：

name: Sync {ContentType} to Frontend

on:
  schedule:
    - cron: '{cron_expression}'  # UTC 时间，注意时区转换
  workflow_dispatch:              # 允许手动触发

permissions:
  contents: write

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0

    - name: Sync content files
      run: |
        set -e
        SRC="{source_directory}"
        DST="{frontend_public_data_path}"
        mkdir -p "$DST"
        if [ -d "$SRC" ]; then
          for dir in "$SRC"/*/; do
            name=$(basename "$dir")
            if [[ "$name" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]]; then
              mkdir -p "$DST/$name"
              cp -f "$dir"*.md "$DST/$name/" 2>/dev/null || true
            fi
          done
        fi

    - name: Rebuild index.json
      run: |
        python3 .agent/skills/auto-page-sync/resources/rebuild_index.py \
          --dir "{frontend_public_data_path}"

    - name: Commit and Push
      run: |
        git config --local user.email "github-actions[bot]@users.noreply.github.com"
        git config --local user.name "github-actions[bot]"
        git pull --rebase || true
        git add {target_paths}
        git diff --quiet && git diff --staged --quiet || \
          (git commit -m "🔄 Auto-sync: {content_type} [deploy]" && git push)

Cron 时间计算：

• 用户说「每天 X 点（北京时间）」→ X - 8 小时 = UTC 时间
• 内容生成时间 + 1 小时 = 同步时间（确保内容已就绪）
• 示例：内容 10:00 生成 → 同步 cron 设为 0 3 * * *（UTC 03:00 = 北京 11:00）

Step 7: SEO 优化（推荐）

1. Sitemap 自动更新 — 在同步脚本中追加新 URL，设置 lastmod 和 changefreq: daily
2. 页面 Meta 标签 — 从 Markdown 标题提取 <title> 和 <meta description>
3. 结构化数据 — 博客型用 Article schema，报告型用 Report schema
4. 内容新鲜度信号 — 页面显示「最后更新时间」，可选生成 RSS Feed

Actions

可用资源文件

• resources/rebuild_index.py — 通用索引重建脚本，可在 GitHub Actions 或本地运行
• resources/sync_workflow_template.yml — GitHub Actions workflow 模板，替换占位符即可用
• resources/report_types_example.json — 报告类型映射示例

完成检查清单

• 内容文件已复制到 public/data/ 并可通过 URL 访问
• index.json 正确列出所有内容条目
• 前端页面能正确渲染 Markdown（含表格、代码块）
• 页面风格与项目整体一致
• 导航栏已添加入口
• GitHub Actions workflow 语法正确
• Cron 时间设置正确（注意 UTC 转换）
• Commit message 包含 [deploy] 触发自动部署
• 无 TypeScript 编译错误

使用示例

示例 1: 每日数据报告

用户输入：
"把 daily-reports/ 目录的报告同步到网站，做成报告页面，每天 11 点更新"

AI 执行：
1. 分析 daily-reports/ → 按日期组织，每天 2 份 Markdown 报告
2. 选择模式 A（日报型）
3. 复制到 public/data/reports/，生成 index.json
4. 创建 /reports/[date] 页面 + report-viewer 组件
5. 导航栏添加「每日报告」
6. 创建 sync_daily_reports.yml，cron: '0 3 * * *'

示例 2: 技术博客

用户输入：
"把 blog/ 目录的文章展示到网站，做成博客，每周一更新"

AI 执行：
1. 分析 blog/ → 按文件组织，Markdown 带 frontmatter
2. 选择模式 B（博客型）
3. 复制到 public/data/blog/，生成 index.json
4. 创建 /blog 列表页 + /blog/[slug] 详情页
5. 导航栏添加「Blog」
6. 创建 sync_blog.yml，cron: '0 0 * * 1'（每周一 UTC 00:00）

示例 3: Landing Page 数据更新

用户输入：
"把 data/stats.json 的数据同步到首页的统计区块，每天更新"

AI 执行：
1. 分析 data/stats.json → 单文件 JSON
2. 选择模式 C（动态区块型）
3. 复制到 public/data/stats.json
4. 修改首页组件读取该 JSON 渲染统计区块
5. 创建 sync_stats.yml，cron: '0 2 * * *'

支持的框架

框架	页面生成	Markdown 渲染	备注
Next.js (App Router)	✅ 完整支持	react-markdown + remark-gfm	推荐
Next.js (Pages Router)	✅ 支持	react-markdown + remark-gfm
Astro	✅ 支持	内置 Markdown 支持
Hugo / Jekyll	✅ 支持	原生 Markdown	静态站点
Vite + React	✅ 支持	react-markdown	需手动路由

注意事项

• 内容源和前端项目在同一仓库时最简单；跨仓库需要在 Actions 中配置多仓库 checkout
• 首次同步大量历史内容时注意 Git commit 大小
• 不同部署平台（Cloudflare Pages / Vercel / Netlify）的自动部署触发方式可能不同
• 确保 Markdown 文件使用 UTF-8 编码