first
This commit is contained in:
289
README.md
Normal file
289
README.md
Normal file
@@ -0,0 +1,289 @@
|
||||
# 📸 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**
|
||||
Reference in New Issue
Block a user