photography-portfolio-template — Eleventy Portfolio Template

SHA-256: b5cb8819a379f16f3a397532fbe4eccfdd0e13e7c3e2a5ffbebd66cbbacef29a

2026-10-01T15:37:37.651Z

# FIELD NOTES Photography Portfolio

[![Verify template](https://github.com/mason2048/photography-portfolio-template/actions/workflows/ci.yml/badge.svg)](https://github.com/mason2048/photography-portfolio-template/actions/workflows/ci.yml)
[![Deploy Pages](https://github.com/mason2048/photography-portfolio-template/actions/workflows/deploy-pages.yml/badge.svg)](https://github.com/mason2048/photography-portfolio-template/actions/workflows/deploy-pages.yml)
[![MIT License](https://img.shields.io/badge/code-MIT-252521.svg)](LICENSE)

一个面向风景、人文与纪实摄影师的开源作品集模板。采用 Eleventy、Pages CMS 和 GitHub Pages，支持专题影集、响应式图片、全屏灯箱、可视化内容维护和自动部署。

- 在线演示：[https://mason2048.github.io/photography-portfolio-template/](https://mason2048.github.io/photography-portfolio-template/)
- English guide: [docs/README.en.md](docs/README.en.md)
- 不需要数据库或付费服务器
- 原片保留在本地，网站自动生成 AVIF、WebP 和 JPEG 响应式版本

## 最快开始

### 方式一：直接创建自己的仓库

1. 点击 [`Use this template`](https://github.com/new?template_name=photography-portfolio-template&template_owner=mason2048)。
2. 创建一个公开仓库。
3. 在新仓库打开 `Settings → Pages`，将 Source 设为 `GitHub Actions`。
4. 等待 `Deploy photography portfolio` 工作流完成。
5. 打开 `https://你的用户名.github.io/你的仓库名/`。

工作流会自动识别用户主页或项目仓库路径，无需手动修改 `/repository-name/`。

### 方式二：下载到本地

需要 Node.js 22 或更新版本：

```bash
npm install
npm run setup
npm run check
npm run dev
```

然后打开 `http://localhost:8080/`。

初始化向导会询问品牌名称、摄影师名称、联系方式和自定义域名。也支持自动化参数：

```bash
npm run setup -- \
  --non-interactive \
  --name="YOUR NAME" \
  --author="YOUR NAME" \
  --title="YOUR NAME — Photography" \
  --contact-url="mailto:[email protected]" \
  --contact-label="Email me"
```

## 使用 Pages CMS 维护影集

1. 打开 [Pages CMS](https://app.pagescms.org/) 并用 GitHub 登录。
2. 授权 Pages CMS GitHub App 访问你创建的仓库。
3. 在“网站资料”中修改首页、摄影师介绍和联系方式。
4. 在“专题影集”中新建专题、上传网页照片并安排照片顺序。
5. 保存后 GitHub Actions 自动重新发布。

每个专题保存在 `content/projects/*.json`，Pages CMS 字段定义位于 [`.pages.yml`](.pages.yml)。完整说明见 [Pages CMS 使用指南](docs/pages-cms.md)。

## 照片工作流

不要把 10MB–50MB 原片直接提交到 GitHub。原片继续存放在硬盘或云盘，仓库只保存最长边 2560px 的网页版本。

macOS：把照片拖到：

```text
tools/prepare-photos.command
```

Windows：把照片拖到：

```text
tools/prepare-photos.cmd
```

所有平台也可以运行：

```bash
npm run photos -- my-project /path/to/photo-01.jpg /path/to/photo-02.heic
```

图片超过 2MB 会显示提醒，超过 5MB 会阻止构建。更多说明见 [照片处理指南](docs/photo-workflow.md)。

## 主要目录

```text
content/projects/        专题数据
assets/images/           网页照片
src/_data/site.json      网站、首页和联系方式
src/                     页面模板与样式
scripts/setup.mjs        初始化向导
scripts/prepare-photos.mjs  照片压缩
.pages.yml               Pages CMS 配置
.github/workflows/       检查与发布
```

## 自定义域名

运行 `npm run setup` 并填写域名，会生成根目录 `CNAME`。随后在 GitHub Pages 和域名服务商中完成 DNS 设置。不要把模板演示仓库的域名复制到自己的仓库。详见 [自定义域名指南](docs/custom-domain.md)。

## 开源许可

- 代码、模板和文档：[MIT License](LICENSE)
- 演示照片：[LICENSE-PHOTOS.md](LICENSE-PHOTOS.md)
- 使用者上传的照片版权仍属于各自摄影师，不会因为使用本模板而变更

## 参与项目

欢迎提交问题、功能建议和 Pull Request。请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)、[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) 与 [SECURITY.md](SECURITY.md)。