Skip to content

Commit b352fc1

Browse files
xkcodingclaude
xkcoding
and
claude
authored
feat: 新增查看原文链接和 CC 协议声明 (#29)
* fix: address Copilot review suggestions for PR #28 - Add avif MIME type support in RSS feed - Add comment explaining enclosure length: 0 rationale - Add width/height attributes to Card thumbnail to prevent CLS Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * feat: add view source link and CC license declaration - Add viewSource config for raw markdown link (GitHub raw URL) - Add license config for CC BY-NC-SA 4.0 declaration - Create ViewSource.astro component with GitHub icon - Create License.astro component with official CC badge and post URL - Integrate components into PostDetails layout - Simplify BackToTopButton and move to TOC sidebar - Add tech stack info to Footer (Astro & AstroPaper) - Remove ShareLinks from post details - Update TableOfContents to support slot for BackToTopButton Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix: 修复无头图文章错误显示动态 OG 图片的问题 - 分离 coverImageUrl（页面显示）和 ogImageUrl（meta 标签） - 页面封面图只在用户明确设置 ogImage 时才显示 - 动态 OG 图片仅用于 meta 标签，不影响页面显示 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: 更新项目文档并归档 OpenSpec proposal - 更新 README.md，添加特性列表和配置说明 - 完善 openspec/project.md 项目上下文 - 归档 add-source-link-and-license proposal - 创建 post-details spec Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * chore: 添加小红书文案生成命令和忽略配置 - 新增 .claude/commands/xhs-copy.md 小红书文案生成命令 - .gitignore 添加 xhs-images/ 目录 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix: 为 CC 协议徽章添加 width/height 属性 避免页面加载时的布局偏移 (CLS) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 91d19d8 commit b352fc1

17 files changed

Lines changed: 625 additions & 68 deletions

File tree

‎.claude/commands/xhs-copy.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
---
2+
description: 根据文章生成小红书文案和标题
3+
allowed-tools: Read, Glob, Grep, Write
4+
argument-hint: <文章路径> [--images <配图目录>]
5+
---
6+
7+
# 小红书文案生成器
8+
9+
根据指定文章生成小红书风格的文案和标题，支持关联已生成的配图。
10+
11+
## 参数说明
12+
13+
| 参数 | 必填 | 说明 | 示例 |
14+
|------|------|------|------|
15+
| `<文章路径>` | 是 | 要生成文案的文章 | `posts/article.md` |
16+
| `--images <目录>` | 否 | 已生成的配图目录 | `--images xhs-images/topic/` |
17+
18+
**示例**：
19+
```bash
20+
# 只生成文案
21+
/xhs-copy posts/article.md
22+
23+
# 生成文案 + 关联配图
24+
/xhs-copy posts/article.md --images xhs-images/slash-command-firecrawl/
25+
```
26+
27+
## 风格定义：实用派技术博主风格
28+
29+
融合苏洋（Soulteary）的写作风格，适配小红书短文案场景。
30+
31+
### 核心原则
32+
33+
| 原则 | 说明 |
34+
|------|------|
35+
| **实用主义** | 解决问题为先，不堆砌概念 |
36+
| **对话感** | 像和朋友聊技术，不像写论文 |
37+
| **有立场** | 敢于推荐或否定，不骑墙 |
38+
| **适量 emoji** | 点缀而非堆砌，每个段落标题一个 |
39+
40+
### 语言规范
41+
42+
**推荐用法**：
43+
- 推荐方案："我选择"、"我的做法是"、"个人用够了"
44+
- 步骤引导："先...再..."、"确认 X 之后"
45+
- 踩坑分享："返回空？加个 timeout，有些网页加载慢"
46+
- 效果验证："如果看到 X 输出，说明配置成功"
47+
- 口语化："够用了"、"一下就完事"、"选哪个不用说了吧"
48+
49+
**禁止用法**：
50+
- 空洞开场："在当今数字化时代"、"随着技术发展"
51+
- 过度修饰："非常"、"极其"、"令人惊叹"
52+
- 假装互动："让我们一起"、"接下来我们将"
53+
- 踩一捧一：不要贬低其他工具来抬高自己的方案
54+
- 过多 emoji：不要每句话都加 emoji
55+
56+
### 结构模板
57+
58+
```
59+
{开头：场景 + 动机，1-2句}
60+
61+
📌 {核心概念解释}
62+
{简短说明，2-3句}
63+
64+
🤔 {为什么选这个方案}
65+
{对比或原因，不踩一捧一}
66+
{一句话总结优势}
67+
68+
📝 {怎么用}：
69+
① 步骤一
70+
② 步骤二
71+
③ ...
72+
73+
⚠️ 踩过的坑：
74+
• {问题}？{解决方案}，{原因}
75+
• ...
76+
77+
{一句话核心思路} ✨
78+
{收尾}
79+
80+
💬 {互动引导}
81+
```
82+
83+
### 标题模板
84+
85+
提供 2 个标题选项：
86+
87+
| 类型 | 格式 | 示例 |
88+
|------|------|------|
89+
| 方案型 | 用 X 实现 Y + emoji | 用 Slash Command 给 Claude Code 加个「抓网页」功能 🔧 |
90+
| 个人视角 | 我给 X 写了个 Y + emoji | 我给 Claude Code 写了个快捷指令，一条命令抓网页 ⚡ |
91+
92+
**避免**：
93+
- "保姆级教程"、"最全指南"（营销味）
94+
- "深入理解"、"完全掌握"（太虚）
95+
- "震惊！"、"居然可以这样"（标题党）
96+
97+
### 标签模板
98+
99+
```
100+
#主题标签1 #主题标签2 #技术干货 #效率提升 #程序员日常
101+
```
102+
103+
---
104+
105+
## 执行步骤
106+
107+
1. **读取文章**：读取用户指定的文章路径
108+
2. **扫描配图**（如指定 `--images`）：
109+
- 列出目录下所有 `.png` / `.jpg` 图片
110+
- 按文件名排序（01-, 02-, ...）
111+
- 读取 `outline.md` 获取每张图的描述（如存在）
112+
3. **分析内容**：
113+
- 提取核心主题和价值点
114+
- 识别目标受众
115+
- 找出可视化/对比点
116+
- 提取踩坑经验
117+
4. **生成文案**：按照上述风格和结构生成小红书文案
118+
5. **生成标题**：提供 2 个标题选项
119+
6. **生成标签**：5-7 个相关标签
120+
7. **输出结果**：以 Markdown 格式输出完整文案 + 配图清单
121+
122+
---
123+
124+
## 输出格式
125+
126+
```markdown
127+
## 小红书文案
128+
129+
### 标题选项
130+
131+
**方案 A**：
132+
> {方案型标题}
133+
134+
**方案 B**：
135+
> {个人视角标题}
136+
137+
---
138+
139+
### 正文
140+
141+
{完整文案}
142+
143+
---
144+
145+
### 标签
146+
147+
{标签列表}
148+
149+
---
150+
151+
### 配图清单（如指定 --images）
152+
153+
| # | 文件名 | 描述 | 建议 |
154+
|---|--------|------|------|
155+
| 1 | 01-cover-xxx.png | 封面 | 作为小红书封面 |
156+
| 2 | 02-content-xxx.png | 内容页 | 第2张图 |
157+
| ... | ... | ... | ... |
158+
159+
**配图目录**：`{配图目录路径}`
160+
**图片数量**：{N} 张
161+
**发布顺序**：按文件名序号 01 → 0N
162+
163+
### 发布建议
164+
165+
| 项目 | 建议 |
166+
|------|------|
167+
| 封面 | 第1张图 |
168+
| 发布时间 | 工作日 12:00-13:00 或 21:00-23:00 |
169+
| 互动 | 评论区放完整代码/文章链接 |
170+
```
171+
172+
---
173+
174+
## 示例输入
175+
176+
```bash
177+
# 只生成文案
178+
/xhs-copy posts/slash-command-firecrawl.md
179+
180+
# 生成文案 + 关联配图
181+
/xhs-copy posts/article.md --images xhs-images/slash-command-firecrawl/
182+
```
183+
184+
## 注意事项
185+
186+
- 文案长度控制在 300-500 字
187+
- 步骤不超过 5 步
188+
- 踩坑点 2-4 个
189+
- 保持口语化，像和朋友聊天
190+
- 不要贬低其他方案，只说自己方案的优点

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,3 +42,5 @@ scripts/migrate-images/reports/
4242

4343
# ossutil output
4444
ossutil_output/
45+
46+
xhs-images/

‎README.md‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,22 @@
22

33
xkcoding 的代码成长日记 - 基于 [Astro](https://astro.build/) + [AstroPaper](https://github.com/satnaing/astro-paper) 主题构建。
44

5+
## 特性
6+
7+
- 🚀 基于 Astro 5.x 构建，性能优异
8+
- 🎨 基于 AstroPaper 主题定制，简洁美观
9+
- 🔍 Pagefind 全文搜索
10+
- 📖 目录侧边栏（TOC）
11+
- 🖼️ 文章封面图 & 动态 OG 图片
12+
- 📝 查看原文（跳转 GitHub raw 文件）
13+
- ⚖️ CC BY-NC-SA 4.0 协议声明
14+
- 🌙 深色模式支持
15+
516
## 技术栈
617

718
- **框架**: Astro 5.x
819
- **主题**: AstroPaper
20+
- **样式**: Tailwind CSS 4.x
921
- **搜索**: Pagefind
1022
- **部署**: GitHub Pages + GitHub Actions
1123

@@ -36,11 +48,27 @@ pnpm run preview
3648
│ ├── data/blog/ # 博客文章 (Markdown)
3749
│ ├── layouts/ # 布局组件
3850
│ ├── pages/ # 页面路由
51+
│ ├── utils/ # 工具函数
3952
│ └── config.ts # 站点配置
53+
├── openspec/ # OpenSpec 规范文档
4054
├── astro.config.ts # Astro 配置
4155
└── package.json
4256
```
4357

58+
## 配置说明
59+
60+
站点配置位于 `src/config.ts`，主要配置项：
61+
62+
- `website`: 站点 URL
63+
- `author`: 作者信息
64+
- `showToc`: 是否显示目录
65+
- `dynamicOgImage`: 是否启用动态 OG 图片
66+
- `editPost`: 编辑文章链接配置
67+
- `viewSource`: 查看原文链接配置
68+
- `license`: 协议声明配置
69+
4470
## License
4571

46-
MIT
72+
文章内容采用 [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/deed.zh-hans) 协议
73+
74+
代码采用 MIT 协议

‎openspec/changes/archive/2026-01-20-add-source-link-and-license/proposal.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Change: 新增查看原文链接和 CC 协议声明
2+
3+
## Why
4+
5+
当前博客文章页面只有"编辑"链接（指向 GitHub edit 页面），缺少以下功能：
6+
1. 读者无法快速查看文章的 Markdown 原始内容（source 模式）
7+
2. 没有明确的版权协议声明，不利于内容保护和合规转载
8+
9+
## What Changes
10+
11+
- 新增"查看原文"链接组件，跳转到 GitHub 仓库文件的 blob 页面（只读模式）
12+
- 新增 CC BY-NC-SA 4.0 协议声明组件，显示在文章正文下方
13+
- 在 `config.ts` 中添加相关配置项（协议类型、仓库 URL 等）
14+
- 修改 `PostDetails.astro` 布局，集成新组件
15+
16+
## Impact
17+
18+
- Affected code:
19+
- `src/config.ts` - 新增配置项
20+
- `src/components/ViewSource.astro` - 新建组件
21+
- `src/components/License.astro` - 新建组件
22+
- `src/layouts/PostDetails.astro` - 集成新组件
23+
- `src/assets/icons/` - 可能需要新增图标

‎openspec/changes/archive/2026-01-20-add-source-link-and-license/specs/post-details/spec.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
## ADDED Requirements
2+
3+
### Requirement: View Source Link
4+
5+
The system SHALL provide a "View Source" link on article detail pages that opens the raw Markdown file in the GitHub repository (blob view, not edit mode).
6+
7+
#### Scenario: User clicks View Source link
8+
9+
- **WHEN** user clicks the "View Source" link on an article page
10+
- **THEN** a new tab opens with the GitHub blob URL for the article's Markdown file
11+
- **AND** the URL format is `https://github.com/{owner}/{repo}/blob/{branch}/{filePath}`
12+
13+
#### Scenario: View Source link visibility
14+
15+
- **WHEN** `SITE.viewSource.enabled` is `true`
16+
- **THEN** the View Source link is displayed on the article page
17+
- **WHEN** `SITE.viewSource.enabled` is `false`
18+
- **THEN** the View Source link is hidden
19+
20+
### Requirement: CC License Declaration
21+
22+
The system SHALL display a Creative Commons license declaration (CC BY-NC-SA 4.0) at the bottom of each article's content area.
23+
24+
#### Scenario: License display position
25+
26+
- **WHEN** an article page is rendered
27+
- **THEN** the CC license declaration appears after the article content
28+
- **AND** before the share links section
29+
30+
#### Scenario: License content elements
31+
32+
- **WHEN** the license component is rendered
33+
- **THEN** it displays:
34+
- The CC BY-NC-SA 4.0 license icon/badge
35+
- A brief license description in Chinese
36+
- A link to the full license text on Creative Commons website
37+
38+
#### Scenario: License visibility control
39+
40+
- **WHEN** `SITE.license.enabled` is `true`
41+
- **THEN** the license declaration is displayed
42+
- **WHEN** `SITE.license.enabled` is `false`
43+
- **THEN** the license declaration is hidden
44+
45+
### Requirement: Configuration Options
46+
47+
The system SHALL provide configuration options in `src/config.ts` for View Source and License features.
48+
49+
#### Scenario: viewSource configuration
50+
51+
- **WHEN** configuring the View Source feature
52+
- **THEN** the following options are available:
53+
- `enabled`: boolean to show/hide the link
54+
- `text`: display text for the link (default: "查看原文")
55+
- `url`: base URL for the repository blob path
56+
57+
#### Scenario: license configuration
58+
59+
- **WHEN** configuring the License feature
60+
- **THEN** the following options are available:
61+
- `enabled`: boolean to show/hide the license
62+
- `type`: license type identifier (e.g., "CC BY-NC-SA 4.0")
63+
- `url`: URL to the full license text

‎openspec/changes/archive/2026-01-20-add-source-link-and-license/tasks.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
## 1. 配置扩展
2+
3+
- [x] 1.1 在 `src/config.ts` 中添加 `viewSource` 配置项（enabled、text、url）
4+
- [x] 1.2 在 `src/config.ts` 中添加 `license` 配置项（enabled、type、url）
5+
6+
## 2. 组件开发
7+
8+
- [x] 2.1 创建 `src/components/ViewSource.astro` 组件
9+
- 接收 `post` 参数，生成 raw URL
10+
- 使用 GitHub 图标
11+
- 样式与 EditPost 保持一致
12+
- [x] 2.2 创建 `src/components/License.astro` 组件
13+
- 显示 CC BY-NC-SA 4.0 协议信息
14+
- 包含协议图标和链接
15+
- 简洁的版权声明文案
16+
17+
## 3. 布局集成
18+
19+
- [x] 3.1 修改 `src/layouts/PostDetails.astro`
20+
- 在文章正文后、分享链接前添加 License 组件
21+
- 在元信息区添加 ViewSource 链接
22+
- [x] 3.2 确保移动端和桌面端响应式显示正常
23+
24+
## 4. 验证
25+
26+
- [x] 4.1 本地构建测试，确保无类型错误
27+
- [x] 4.2 验证链接跳转正确（raw 页面）
28+
- [x] 4.3 检查暗色/亮色模式下样式正常

0 commit comments

Comments
 (0)