laowang/astro-photography-portfolio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
astro-photography-portfolio/README.md
laowang 82a13f4aad first
2025-11-26 13:48:13 +08:00

8.0 KiB
Raw Permalink Blame History

📸 Astro Photography Portfolio Template

A modern, fast, and highly customizable photography portfolio template built with Astro. 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 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:
npm install
# or
yarn install
  1. Start the development server:
npm run dev
# or
yarn dev

📝 Make it your own

Configuration

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

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

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

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

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 View Git Blame Copy Permalink