Skip to content

Commit 5a5cf6d

Browse files
magic-altmagic-alt
committed
完整功能集成：评论（Talkyard）、表单（Formspree）、搜索（Algolia）
1 parent 793aab3 commit 5a5cf6d

File tree

9 files changed

+894
-6
lines changed

9 files changed

+894
-6
lines changed

‎.github/workflows/algolia.yml‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
name: Update Algolia Index
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- '_posts/**'
9+
- '*.md'
10+
- '_config.yml'
11+
12+
jobs:
13+
update_index:
14+
runs-on: ubuntu-latest
15+
name: Update Algolia search index
16+
steps:
17+
- name: Checkout repository
18+
uses: actions/checkout@v3
19+
with:
20+
fetch-depth: 1
21+
22+
- name: Set up Ruby
23+
uses: ruby/setup-ruby@v1
24+
with:
25+
ruby-version: '3.1'
26+
bundler-cache: true
27+
28+
- name: Install dependencies
29+
run: bundle install
30+
31+
- name: Update Algolia index
32+
env:
33+
ALGOLIA_API_KEY: ${{ secrets.ALGOLIA_ADMIN_API_KEY }}
34+
run: |
35+
if [ -z "$ALGOLIA_API_KEY" ]; then
36+
echo "⚠️ ALGOLIA_ADMIN_API_KEY secret not configured"
37+
echo "Please add your Algolia Admin API Key to repository secrets"
38+
echo "Settings -> Secrets and variables -> Actions -> New repository secret"
39+
echo "Name: ALGOLIA_ADMIN_API_KEY"
40+
exit 0
41+
fi
42+
43+
echo "🔍 Indexing content to Algolia..."
44+
bundle exec jekyll algolia
45+
46+
- name: Workflow summary
47+
if: always()
48+
run: |
49+
echo "## Algolia Index Update" >> $GITHUB_STEP_SUMMARY
50+
echo "" >> $GITHUB_STEP_SUMMARY
51+
if [ -z "${{ secrets.ALGOLIA_ADMIN_API_KEY }}" ]; then
52+
echo "⚠️ **Status**: Skipped (API key not configured)" >> $GITHUB_STEP_SUMMARY
53+
echo "" >> $GITHUB_STEP_SUMMARY
54+
echo "### Configuration Required" >> $GITHUB_STEP_SUMMARY
55+
echo "" >> $GITHUB_STEP_SUMMARY
56+
echo "1. Get your Admin API Key from Algolia dashboard" >> $GITHUB_STEP_SUMMARY
57+
echo "2. Go to repository **Settings** → **Secrets and variables** → **Actions**" >> $GITHUB_STEP_SUMMARY
58+
echo "3. Click **New repository secret**" >> $GITHUB_STEP_SUMMARY
59+
echo "4. Name: \`ALGOLIA_ADMIN_API_KEY\`" >> $GITHUB_STEP_SUMMARY
60+
echo "5. Value: Paste your Admin API Key" >> $GITHUB_STEP_SUMMARY
61+
else
62+
echo "✅ **Status**: Index updated successfully" >> $GITHUB_STEP_SUMMARY
63+
echo "" >> $GITHUB_STEP_SUMMARY
64+
echo "Search index has been synchronized with the latest content." >> $GITHUB_STEP_SUMMARY
65+
fi

‎ADVANCED-FEATURES-SETUP.md‎

Lines changed: 287 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,287 @@
1+
# 高级功能配置指南
2+
3+
本指南介绍如何配置博客的评论、表单和搜索功能。
4+
5+
## 📋 功能清单
6+
7+
- ✅ **评论系统**: Talkyard（免费，无需自建服务器）
8+
- ✅ **联系表单**: Formspree（免费额度：50次/月）
9+
- ✅ **全文搜索**: Algolia（免费额度：10k搜索/月）
10+
11+
---
12+
13+
## 1. 配置 Talkyard 评论系统
14+
15+
### 1.1 注册账号
16+
17+
1. 访问 [Talkyard](https://www.talkyard.io/)
18+
2. 点击 **Sign Up** 注册账号
19+
3. 创建新的 Community/Forum
20+
21+
### 1.2 获取配置参数
22+
23+
1. 进入你的 Talkyard 管理后台
24+
2. 找到 **Settings** → **Embedded Comments**
25+
3. 获取以下信息：
26+
- **Server URL**: 类似 `https://comments-for-yourblog.talkyard.net`
27+
- **Site ID**: 数字 ID（如 `1`）
28+
29+
### 1.3 更新配置文件
30+
31+
编辑 `_config.yml`，找到 `talkyard` 部分：
32+
33+
```yaml
34+
talkyard:
35+
server_url: 'https://comments-for-yourblog.talkyard.net'
36+
site_id: 1
37+
```
38+
39+
### 1.4 测试评论功能
40+
41+
1. 提交配置到 GitHub
42+
2. 等待 GitHub Pages 构建完成（约1-2分钟）
43+
3. 访问任意博客文章页面
44+
4. 页面底部应显示 Talkyard 评论框
45+
46+
### 1.5 控制评论显示
47+
48+
**全局禁用评论**（在 `_config.yml`）：
49+
```yaml
50+
comments: false
51+
```
52+
53+
**单篇文章禁用评论**（在文章头部 Front Matter）：
54+
```yaml
55+
---
56+
title: "文章标题"
57+
comments: false
58+
---
59+
```
60+
61+
---
62+
63+
## 2. 配置 Formspree 表单
64+
65+
### 2.1 注册账号
66+
67+
1. 访问 [Formspree](https://formspree.io/)
68+
2. 点击 **Sign Up** 注册（可用 GitHub 账号登录）
69+
3. 免费计划：50次表单提交/月
70+
71+
### 2.2 创建表单
72+
73+
1. 登录后点击 **New Form**
74+
2. 输入表单名称：如 `Contact Form`
75+
3. 获得 Form ID：类似 `xpznabcd`（8位随机字符）
76+
77+
### 2.3 配置表单设置
78+
79+
在 Formspree 后台：
80+
- ✅ **Email Notifications**: 开启邮件通知
81+
- ✅ **Spam Filter**: 开启垃圾邮件过滤
82+
- ✅ **File Uploads**: 根据需要决定是否允许附件
83+
84+
### 2.4 更新配置文件
85+
86+
编辑 `_config.yml`，找到 `formspree` 部分：
87+
88+
```yaml
89+
formspree:
90+
form_id: xpznabcd # 替换为你的实际 Form ID
91+
```
92+
93+
### 2.5 测试表单
94+
95+
1. 提交配置到 GitHub
96+
2. 访问 `/contact/` 页面
97+
3. 填写表单提交测试
98+
4. 应跳转到 `/thank-you/` 页面
99+
5. 检查你的邮箱是否收到提交通知
100+
101+
---
102+
103+
## 3. 配置 Algolia 搜索
104+
105+
### 3.1 注册账号
106+
107+
1. 访问 [Algolia](https://www.algolia.com/)
108+
2. 点击 **Sign Up** 注册（可用 GitHub 账号登录）
109+
3. 选择免费计划：10,000 次搜索/月
110+
111+
### 3.2 创建应用和索引
112+
113+
1. 在 Dashboard 创建新应用：如 `my-blog`
114+
2. 创建索引（Index）：如 `blog_posts`
115+
3. 索引名称建议使用小写和下划线
116+
117+
### 3.3 获取 API Keys
118+
119+
在 **Settings** → **API Keys** 页面：
120+
121+
- **Application ID**: 类似 `5GZNQJ7W8M`（10位大写字母+数字）
122+
- **Search-Only API Key**: 公开使用的只读密钥（前端安全）
123+
- **Admin API Key**: 管理密钥（仅用于索引更新，**不要公开**）
124+
125+
### 3.4 更新配置文件
126+
127+
编辑 `_config.yml`，找到 `algolia` 部分：
128+
129+
```yaml
130+
algolia:
131+
application_id: 5GZNQJ7W8M # 替换为你的 Application ID
132+
index_name: blog_posts # 替换为你的索引名称
133+
search_only_api_key: 8a8d3...f9c2e # 替换为你的 Search-Only API Key
134+
```
135+
136+
⚠️ **重要**: `search_only_api_key` 是公开的，不要使用 Admin API Key！
137+
138+
### 3.5 配置 GitHub Secret
139+
140+
Admin API Key 用于自动更新索引，需要添加到 GitHub Secrets：
141+
142+
1. 进入你的 GitHub 仓库
143+
2. **Settings** → **Secrets and variables** → **Actions**
144+
3. 点击 **New repository secret**
145+
4. Name: `ALGOLIA_ADMIN_API_KEY`
146+
5. Value: 粘贴你的 Admin API Key
147+
6. 点击 **Add secret**
148+
149+
### 3.6 手动索引（首次或测试）
150+
151+
在本地运行（需要先 `bundle install`）：
152+
153+
```bash
154+
# Windows PowerShell
155+
$env:ALGOLIA_API_KEY="你的Admin_API_Key"
156+
bundle exec jekyll algolia
157+
158+
# macOS/Linux
159+
export ALGOLIA_API_KEY="你的Admin_API_Key"
160+
bundle exec jekyll algolia
161+
```
162+
163+
成功后会看到：
164+
```
165+
Indexing 15 records...
166+
✔ All records indexed!
167+
```
168+
169+
### 3.7 自动索引
170+
171+
配置完 GitHub Secret 后，每次推送代码到 `main` 分支：
172+
- 自动触发 `.github/workflows/algolia.yml`
173+
- 更新 Algolia 索引
174+
- 在 **Actions** 标签查看运行日志
175+
176+
### 3.8 测试搜索
177+
178+
1. 提交所有配置到 GitHub
179+
2. 等待 Actions 运行完成
180+
3. 访问 `/search/` 页面
181+
4. 输入关键词测试搜索功能
182+
183+
---
184+
185+
## 📊 配置检查清单
186+
187+
### Talkyard
188+
- [ ] 已注册 Talkyard 账号
189+
- [ ] 已创建 Community
190+
- [ ] 已获取 `server_url` 和 `site_id`
191+
- [ ] 已更新 `_config.yml`
192+
- [ ] 已测试评论显示正常
193+
194+
### Formspree
195+
- [ ] 已注册 Formspree 账号
196+
- [ ] 已创建表单并获取 Form ID
197+
- [ ] 已更新 `_config.yml` 中的 `form_id`
198+
- [ ] 已开启邮件通知
199+
- [ ] 已测试表单提交成功
200+
201+
### Algolia
202+
- [ ] 已注册 Algolia 账号
203+
- [ ] 已创建应用和索引
204+
- [ ] 已获取 Application ID 和 API Keys
205+
- [ ] 已更新 `_config.yml` 的三个参数
206+
- [ ] 已添加 `ALGOLIA_ADMIN_API_KEY` 到 GitHub Secrets
207+
- [ ] 已完成首次索引（手动或自动）
208+
- [ ] 已测试搜索功能正常
209+
210+
---
211+
212+
## 🔧 故障排查
213+
214+
### Talkyard 评论不显示
215+
216+
1. 检查浏览器控制台（F12）是否有 JavaScript 错误
217+
2. 确认 `server_url` 格式正确（包含 https://）
218+
3. 确认 `site_id` 是纯数字，不带引号
219+
4. 访问 Talkyard 管理后台检查配置
220+
221+
### Formspree 表单无法提交
222+
223+
1. 确认 `form_id` 格式正确（8位字符）
224+
2. 检查 Formspree 后台是否有提交记录
225+
3. 确认邮箱地址有效
226+
4. 查看垃圾邮件文件夹
227+
228+
### Algolia 搜索无结果
229+
230+
1. 访问 Algolia Dashboard 检查索引记录数
231+
2. 确认 `application_id` 和 `index_name` 正确
232+
3. 检查 GitHub Actions 运行日志：`Actions` → `Update Algolia Index`
233+
4. 手动运行 `bundle exec jekyll algolia` 测试
234+
5. 确认 `search_only_api_key` 权限正确（只读权限）
235+
236+
### GitHub Actions 失败
237+
238+
**Algolia 索引失败**:
239+
- 检查 `ALGOLIA_ADMIN_API_KEY` 是否正确添加到 Secrets
240+
- 确认 Admin API Key 有写入权限
241+
- 查看 Actions 日志的详细错误信息
242+
243+
**IndexNow 通知失败**:
244+
- 检查 `INDEXNOW_KEY` 是否添加到 Secrets
245+
- 确认 key 文件已上传到网站根目录
246+
247+
---
248+
249+
## 🎯 最佳实践
250+
251+
### 安全建议
252+
253+
1. ✅ **永远不要**把 Admin API Key 提交到代码仓库
254+
2. ✅ 使用 GitHub Secrets 存储敏感密钥
255+
3. ✅ 定期轮换 API Keys
256+
4. ✅ 为 Formspree 开启 reCAPTCHA（防机器人）
257+
258+
### 性能优化
259+
260+
1. Algolia 索引仅在 `_posts/**` 或 `*.md` 文件变更时触发
261+
2. 评论系统按需加载，不影响页面初始性能
262+
3. 搜索使用 CDN 加速，全球访问快速
263+
264+
### 内容管理
265+
266+
1. 使用 Front Matter `comments: false` 控制单篇文章评论
267+
2. 定期清理 Formspree 提交记录
268+
3. 监控 Algolia 搜索分析优化关键词
269+
270+
---
271+
272+
## 📚 相关文档
273+
274+
- [Talkyard 文档](https://www.talkyard.io/docs)
275+
- [Formspree 文档](https://help.formspree.io/)
276+
- [Algolia Jekyll Plugin](https://community.algolia.com/jekyll-algolia/)
277+
- [GitHub Actions 文档](https://docs.github.com/actions)
278+
279+
---
280+
281+
## ❓ 需要帮助？
282+
283+
如遇到问题：
284+
1. 检查本文档的故障排查部分
285+
2. 查看各服务的官方文档
286+
3. 检查 GitHub Actions 运行日志
287+
4. 在浏览器控制台查看错误信息

‎Gemfile‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ group :jekyll_plugins do
99
gem "jekyll-seo-tag", "~> 2.8"
1010
gem "jekyll-sitemap", "~> 1.4"
1111
gem "jekyll-last-modified-at", "~> 1.3"
12+
gem "jekyll-remote-theme", "~> 0.4" # 远程主题支持
13+
gem "jekyll-algolia", "~> 1.8" # Algolia 搜索
1214
end
1315

1416
# Allow running `bundle exec jekyll serve` on Ruby >= 3.0

0 commit comments

Comments
 (0)