astro-photography-portfolio/README.md

# 📸 Astro Photography Portfolio Template



A modern, fast, and highly customizable photography portfolio template built with [Astro](https://astro.build).
Ideal for photographers who want to showcase their work through a sleek, performant, and professional website.



## ✨ Features

- Lightning-fast performance with Astro
- Fully responsive design
- Optimized image loading and handling
- Easy to customize
- Easy to organized gallery via a yaml file
- Multiple albums support
- Image zoom capabilities
- Automatic deployment to GitHub pages
- Script to automatically create a gallery from images

## 🚀 Getting Started

### Prerequisites

- Check [AstroJS](https://docs.astro.build/en/install-and-setup/) documentation for prerequisites
- Basic knowledge of Astro and web development

### Installation

1. click "Use this template" on GitHub
2. Clone your newly created template
3. Install dependencies:

```bash
npm install
# or
yarn install
```

3. Start the development server:

```bash
npm run dev
# or
yarn dev
```

## 📝 Make it your own

### Configuration

Edit the `astro.config.ts` file to update your github pages details:

```typescript
export default defineConfig({
  site: '<github pages domain>',
  base: '<repository name>',
  // ...
});
```

Edit the `site.config.mts` file to update your personal information:

```typescript
export default {
  title: 'SR',
  favicon: 'favicon.ico',
  owner: 'Sara Richard',
  // ... Other configurations
};
```

### Customize site icon

Replace `public/favicon.ico` with your icon and change the configuration
if your file has a different name/location.

### Customize the About page

- Replace the profile image (see [site.config.mts](site.config.mts) for configuration)
- Edit content in [about page](./src/pages/about.astro)

### Adding Your Photos

1. Place your images in the `src/gallery/<album>` directory
2. Update the gallery details in `src/gallery/gallery.yaml`. Optionally, you can run `npm run generate` to generate a
   gallery.yaml file from the images in the directory.
3. Update meta-data for images in the `src/gallery/gallery.yaml` file.
4. Images are automatically optimized during build

### Adding photos to the featured section

"featured" is a builtin collection, and images can be added to it by specifying it in the collections parameter like any
other collection.



# 📸 Phase 1 二次开发技术文档



项目名称: Astro Photography Portfolio (Customized)

版本: Phase 1 Completed

日期: 2025-11-26



## 1. 核心功能变更概览



本次二次开发主要针对原版模版进行了跨平台兼容性修复、国际化 (i18n) 重构、视觉交互升级以及性能优化。



### 🛠️ 系统与脚本优化



1. **跨平台路径修复 (`npm run generate`)**
   - **问题**: 原脚本在 Windows 下生成的 `gallery.yaml` 路径包含反斜杠 `\`，导致 Astro 在 Linux/Mac 环境或部署时无法识别图片。
   - **解决**: 修改 `src/data/gallery-generator.ts`，引入 `toUnixPath` 函数，强制将所有路径分隔符转换为 Unix 风格 `/`。
   - **新增**: 脚本现在会自动识别文件名中包含 `_featured` 的图片，并自动添加 `featured` 标签。
   - **新增**: 图片生成顺序改为按 EXIF 拍摄时间倒序排列（最新的在前）。
2. **EXIF 数据透传与展示**
   - **问题**: 原版 `gallery.yaml` 虽然有 EXIF 数据，但前端并未读取和展示。
   - **解决**:
     - 修改 `src/data/galleryData.ts` 和 `imageStore.ts`，确保 `exif` 对象被完整传递给前端组件。
     - 修改 `src/data/imageStore.ts` 中的 `builtInCollections`，添加 `cover` 到白名单，防止报错。
     - 修改 `src/components/PhotoGrid.astro`，格式化 EXIF 数据 (相机、焦段、光圈、ISO) 并注入到 Lightbox (GLightbox) 的描述中。
3. **性能优化 (缩略图策略)**
   - **优化**: 在 `PhotoGrid.astro` 中，强制使用 Astro 的 `<Image width={720} ... />` 组件。
   - **效果**: 首页和列表页不再加载几千像素的原图，而是加载自动生成的 WebP 缩略图，大幅提升加载速度。



### 🌍 国际化 (i18n) 重构



1. **目录结构变更**
   - 原 `src/pages/*` 下的文件被移动至 `src/pages/zh/` (中文版) 和 `src/pages/en/` (英文版)。
   - 根目录 `src/pages/index.astro` 仅作为重定向器，根据 `base` 路径自动跳转至默认语言 `/zh/`。
   - 组件引用的 Import 路径已全部修正为相对路径 (`../../../` 等)。
2. **双语支持**
   - 新建 `src/i18n/ui.ts` 管理翻译字典。
   - `src/components/NavBar.astro` 支持语言切换按钮，自动根据当前 URL 切换 `/zh/` 和 `/en/` 前缀。
   - 首页组件 (`LandingHero`, `FeaturedGallery`) 被改造为支持 `props` 传参，允许在不同语言的 `index.astro` 中传入对应的翻译文案。



### 🎨 UI 与视觉升级



1. **全屏动态轮播背景 (`HeroBackground`)**
   - 新建 `src/components/HeroBackground.astro` 组件。
   - **逻辑**: 自动读取 `gallery.yaml` 中包含 `cover` 标签的图片。如果未找到，则回退显示前 3 张图片。
   - **效果**: 全屏淡入淡出轮播，并添加深色遮罩以保证前景文字可读性。
2. **自适应导航栏 (`NavBar`)**
   - **逻辑**: 页面顶部时背景透明、文字白色（配合深色轮播图）；向下滚动后背景变白、文字变黑（保证阅读清晰度）。
   - **修复**: 解决了 Astro Frontmatter 格式错误导致的页面顶部出现白色空白条和 `---` 符号的问题。

------



## 2. 使用指南 (给用户/朋友)





### 如何管理图片



所有操作均在 `src/gallery/gallery.yaml` 或文件系统中进行。

1. **添加新图片**: 将图片放入 `src/gallery/xxx/` 文件夹。
2. **生成数据**: 运行 `npm run generate`。
3. **设置精选 (Featured)**:
   - 方法 A: 图片文件名包含 `_featured` (如 `img_featured.jpg`)，重新运行脚本。
   - 方法 B: 在 `gallery.yaml` 中手动给图片添加 `- featured` 标签。
4. **设置首页轮播图 (Cover)**:
   - 在 `gallery.yaml` 中手动给图片添加 `- cover` 标签。
   - *注意*: `cover` 标签不会出现在网站的分类过滤器中，仅用于首页背景。

------



## 3. 开发指南：如何添加新菜单项



如果你想添加一个全新的页面（例如：“视频 / Video”），请严格按照以下步骤操作：



### 第一步：创建页面文件



你需要分别为中文版和英文版创建页面文件。

1. **中文版**: 新建 `src/pages/zh/video.astro`

   代码段

   ```
   ---
   import MainLayout from '../../layouts/MainLayout.astro';
   ---
   <MainLayout lang="zh" title="视频作品">
       <div class="container mx-auto py-20">
           <h1>我的视频</h1>
           </div>
   </MainLayout>
   ```

2. **英文版**: 新建 `src/pages/en/video.astro` (内容同上，语言改 `lang="en"`)。



### 第二步：定义菜单名称



打开 `src/i18n/ui.ts`，在字典中添加新菜单的翻译。

TypeScript

```
export const ui = {
    zh: {
        'nav.home': '首页',
        'nav.gallery': '作品集',
        'nav.about': '关于我',
        'nav.video': '视频', // <--- 新增
    },
    en: {
        'nav.home': 'Home',
        'nav.gallery': 'Gallery',
        'nav.about': 'About',
        'nav.video': 'Video', // <--- 新增
    },
};
```



### 第三步：添加到导航栏



打开 `src/components/NavBar.astro`，将新项加入 `menuItems` 数组。

TypeScript

```
// ...
const menuItems = [
    { name: t['nav.home'], link: homePath },
    { name: t['nav.gallery'], link: `${homePath}/collections` },
    // 新增下面这一行
    { name: t['nav.video'], link: `${homePath}/video` }, 
    { name: t['nav.about'], link: `${homePath}/about` },
];
// ...
```

------



## 4. 已知待优化项 (Phase 2 计划)



1. **分类名称国际化**: 目前分类显示为文件夹名称（英文），尚未对接翻译字典。
2. **CMS 后台集成**: 计划集成 Decap CMS，实现图形化管理图片和配置，无需接触代码。

------

**Document End**