blog-code/docs/CONTENT_REPOSITORY.md

Mizuki 内容仓库结构说明

本文档说明如何创建和组织 Mizuki 博客的内容仓库。

📁 推荐的目录结构

Mizuki-Content/
├── posts/              # 博客文章
│   ├── post-1.md
│   ├── post-2.md
│   └── my-article/
│       ├── index.md
│       └── cover.jpg
├── spec/               # 特殊页面
│   ├── about.md
│   └── friends.md
├── data/               # 数据文件
│   ├── anime.ts
│   ├── projects.ts
│   ├── skills.ts
│   └── timeline.ts
├── images/             # 图片资源
│   ├── albums/         # 相册图片
│   ├── diary/          # 日记图片
│   └── posts/          # 文章图片
└── README.md

🚀 快速开始

1. 创建新的内容仓库

# 创建新仓库
mkdir Mizuki-Content
cd Mizuki-Content
git init

# 创建基本目录结构
mkdir -p posts spec data images/albums images/diary images/posts

# 创建 README
echo "# Mizuki 博客内容" > README.md

2. 从现有 Mizuki 项目迁移内容

如果你已经有一个 Mizuki 项目,可以将内容迁移到新仓库:

# 在 Mizuki 项目根目录执行
cd /path/to/Mizuki

# 复制内容到新仓库
cp -r src/content/posts/* /path/to/Mizuki-Content/posts/
cp -r src/content/spec/* /path/to/Mizuki-Content/spec/
cp -r src/data/* /path/to/Mizuki-Content/data/
cp -r public/images/* /path/to/Mizuki-Content/images/

3. 提交到 Git

cd /path/to/Mizuki-Content

git add .
git commit -m "Initial commit: Add blog content"

# 添加远程仓库并推送
git remote add origin https://github.com/your-username/Mizuki-Content.git
git branch -M main
git push -u origin main

🔗 连接到 Mizuki 代码仓库

方式一: Git Submodule (推荐)

在 Mizuki 代码仓库中:

cd /path/to/Mizuki

# 添加内容仓库作为 submodule
git submodule add https://github.com/your-username/Mizuki-Content.git content

# 提交 submodule 配置
git add .gitmodules content
git commit -m "Add content repository as submodule"
git push

配置环境变量 .env:

CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
USE_SUBMODULE=true

方式二: 独立仓库模式

配置环境变量 .env:

CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
CONTENT_DIR=./content
USE_SUBMODULE=false

然后运行同步:

pnpm run sync-content

📝 内容编写指南

文章前言 (Frontmatter)

每篇文章都应该包含以下前言:

---
title: 文章标题
published: 2024-01-01
description: 文章描述
image: ./cover.jpg
tags: [标签1, 标签2]
category: 分类
draft: false
pinned: false
lang: zh-CN
---

目录组织

• 单文件文章: 直接在 posts/ 目录下创建 .md 文件
• 包含图片的文章: 创建文件夹,将 index.md 和图片放在一起

示例:

posts/
├── simple-post.md                    # 简单文章
└── complex-post/                     # 复杂文章
    ├── index.md                      # 文章内容
    ├── cover.jpg                     # 封面图
    └── diagram.png                   # 文章中的图片

🔄 更新工作流

本地开发

1. 修改内容仓库中的文件
2. 提交并推送更改
3. 在代码仓库中同步内容:

   cd /path/to/Mizuki
   pnpm run sync-content
   

使用 Submodule 时

# 更新 submodule
cd /path/to/Mizuki
git submodule update --remote --merge

# 或者使用同步脚本
pnpm run sync-content

部署时自动同步

在 CI/CD 配置中添加:

- name: Sync Content
  run: pnpm run sync-content
  env:
    CONTENT_REPO_URL: ${{ secrets.CONTENT_REPO_URL }}
    USE_SUBMODULE: true

📦 数据文件说明

anime.ts

番剧数据配置,包含你观看的动画列表。

projects.ts

项目展示数据,展示你的作品集。

skills.ts

技能数据,展示你的技术栈。

timeline.ts

时间线数据,记录重要事件。

🎨 图片管理

目录说明

• images/albums/: 相册页面的图片
• images/diary/: 日记页面的图片
• images/posts/: 文章中引用的公共图片

图片引用

在文章中引用图片:

<!-- 相对路径 (推荐) -->
![描述](./image.jpg)

<!-- 公共图片目录 -->
![描述](/images/posts/image.jpg)

⚠️ 注意事项

1. 不要在内容仓库中包含代码文件
2. 保持目录结构与主仓库一致
3. 定期备份重要内容
4. 使用 Git LFS 管理大型图片文件(可选)

🔐 私有内容仓库

如果你的内容仓库是私有的，需要配置访问权限。详细的配置方法请参考：

• 内容分离完整指南 - 私有仓库配置
• 部署指南 - 各平台的私有仓库部署配置

快速参考

本地开发: 推荐使用 SSH 密钥

CONTENT_REPO_URL=git@github.com:your-username/Mizuki-Content-Private.git
USE_SUBMODULE=true

CI/CD 部署: 根据平台选择

• GitHub Actions: 使用 GITHUB_TOKEN (同账号) 或 SSH 密钥
• Vercel/Netlify: 授权访问或使用 Token

📚 参考资源

• Git Submodule 文档
• Mizuki 文档
• Astro Content Collections

---

💡 提示: 建议先在本地测试内容同步流程,确保一切正常后再配置自动化部署。