256 lines
5.6 KiB
Markdown
256 lines
5.6 KiB
Markdown
# 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. 创建新的内容仓库
|
|
|
|
```bash
|
|
# 创建新仓库
|
|
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 项目,可以将内容迁移到新仓库:
|
|
|
|
```bash
|
|
# 在 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
|
|
|
|
```bash
|
|
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 代码仓库中:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
|
|
USE_SUBMODULE=true
|
|
```
|
|
|
|
### 方式二: 独立仓库模式
|
|
|
|
配置环境变量 `.env`:
|
|
|
|
```bash
|
|
CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
|
|
CONTENT_DIR=./content
|
|
USE_SUBMODULE=false
|
|
```
|
|
|
|
然后运行同步:
|
|
|
|
```bash
|
|
pnpm run sync-content
|
|
```
|
|
|
|
## 📝 内容编写指南
|
|
|
|
### 文章前言 (Frontmatter)
|
|
|
|
每篇文章都应该包含以下前言:
|
|
|
|
```yaml
|
|
---
|
|
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. 在代码仓库中同步内容:
|
|
```bash
|
|
cd /path/to/Mizuki
|
|
pnpm run sync-content
|
|
```
|
|
|
|
### 使用 Submodule 时
|
|
|
|
```bash
|
|
# 更新 submodule
|
|
cd /path/to/Mizuki
|
|
git submodule update --remote --merge
|
|
|
|
# 或者使用同步脚本
|
|
pnpm run sync-content
|
|
```
|
|
|
|
### 部署时自动同步
|
|
|
|
在 CI/CD 配置中添加:
|
|
|
|
```yaml
|
|
- 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/`: 文章中引用的公共图片
|
|
|
|
### 图片引用
|
|
|
|
在文章中引用图片:
|
|
|
|
```markdown
|
|
<!-- 相对路径 (推荐) -->
|
|
|
|
|
|
<!-- 公共图片目录 -->
|
|
|
|
```
|
|
|
|
## ⚠️ 注意事项
|
|
|
|
1. **不要**在内容仓库中包含代码文件
|
|
2. **保持**目录结构与主仓库一致
|
|
3. **定期**备份重要内容
|
|
4. **使用** Git LFS 管理大型图片文件(可选)
|
|
|
|
## 🔐 私有内容仓库
|
|
|
|
如果你的内容仓库是私有的，需要配置访问权限。详细的配置方法请参考：
|
|
|
|
- [内容分离完整指南 - 私有仓库配置](./CONTENT_SEPARATION.md#-私有仓库配置)
|
|
- [部署指南](./DEPLOYMENT.md) - 各平台的私有仓库部署配置
|
|
|
|
### 快速参考
|
|
|
|
**本地开发**: 推荐使用 SSH 密钥
|
|
```bash
|
|
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 文档](https://git-scm.com/book/zh/v2/Git-%E5%B7%A5%E5%85%B7-%E5%AD%90%E6%A8%A1%E5%9D%97)
|
|
- [Mizuki 文档](https://docs.mizuki.mysqil.com/)
|
|
- [Astro Content Collections](https://docs.astro.build/zh-cn/guides/content-collections/)
|
|
|
|
---
|
|
|
|
💡 **提示**: 建议先在本地测试内容同步流程,确保一切正常后再配置自动化部署。
|