Skip to content

Commit 61da3ce

Browse files
guqingguqing
authored
chore: update README (#56)
1 parent e39d438 commit 61da3ce

File tree

2 files changed

+101
-129
lines changed

2 files changed

+101
-129
lines changed

‎README.md‎

Lines changed: 12 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -1,137 +1,20 @@
1-
# plugin-feed
1+
# RSS 订阅插件
22

33
Halo 2.0 的 RSS 订阅链接生成插件
44

5-
## 如何扩展 RSS 源
5+
## 如何使用
66

7-
> 从 feed 插件 v1.4.0 版本开始，支持扩展 RSS 功能。
7+
RSS 订阅插件提供了用于生成 RSS 订阅链接的功能， 默认提供了以下订阅链接类型：
88

9-
`feed` 插件提供了扩展点，允许其他插件扩展 RSS 源。
10-
11-
### 步骤 1：在插件中引入 feed 依赖
12-
13-
在你的插件项目中添加 `feed` 插件的依赖：
14-
15-
```groovy
16-
dependencies {
17-
// ...
18-
compileOnly "run.halo.feed:api:{version}"
19-
}
20-
```
21-
22-
将 `{version}` 替换为实际的 `feed` 插件版本号。
23-
24-
### 步骤 2：实现 `RssRouteItem` 扩展点接口
25-
26-
创建一个类实现 `run.halo.feed.RssRouteItem` 接口，提供自定义的 RSS 数据源。例如：
27-
28-
```java
29-
public class MomentRssProvider implements RssRouteItem {
30-
// 实现具体的 RSS 提供逻辑
31-
}
32-
```
33-
34-
你可以参考 [PostRssProvider](./app/src/main/java/run/halo/feed/provider/PostRssProvider.java) 示例。
35-
36-
### 步骤 3：声明扩展点
37-
38-
在 `src/main/resources/extensions`
39-
目录下，声明你的扩展。你可以参考 [ext-definition.yaml](app/src/main/resources/extensions/ext-definition.yaml) 文件来完成此步骤。
40-
41-
### 步骤 4：定义配置类并清理 RSS 缓存
42-
43-
在插件中定义一个配置类，使用 `@ConditionalOnClass` 注解确保只有在 `run.halo.feed.RssRouteItem` 类存在时才会创建对应的
44-
Bean。同时，定义事件监听器来清理缓存。
45-
46-
`@ConditionalOnClass` 注解只能使用 name 属性来指定类全限定名，不支持使用 value 属性。
47-
48-
示例代码：
49-
50-
```java
51-
52-
@Configuration
53-
@ConditionalOnClass(name = "run.halo.feed.RssRouteItem")
54-
@RequiredArgsConstructor
55-
public class RssAutoConfiguration {
56-
private final ApplicationEventPublisher eventPublisher;
57-
58-
@Bean
59-
public MomentRssProvider momentRssProvider() {
60-
return new MomentRssProvider();
61-
}
62-
63-
@Async
64-
@EventListener({MomentUpdatedEvent.class, MomentDeletedEvent.class})
65-
public void onMomentUpdatedOrDeleted() {
66-
var rule = CacheClearRule.forExact("/feed/moments/rss.xml");
67-
var event = RssCacheClearRequested.forRule(this, rule);
68-
eventPublisher.publishEvent(event);
69-
}
70-
}
71-
```
72-
73-
此配置确保了当 `RssRouteItem` 接口存在时，插件才会自动创建 `MomentRssProvider` 并监听相关事件来清理缓存。
74-
75-
### 步骤 5：声明插件依赖
76-
77-
在 `plugin.yaml` 文件中声明 `feed` 插件为可选依赖，确保当 `feed` 插件存在并启用时，插件能够自动注册 RSS 源。
78-
79-
```yaml
80-
apiVersion: plugin.halo.run/v1alpha1
81-
kind: Plugin
82-
metadata:
83-
name: moment
84-
spec:
85-
pluginDependencies:
86-
"PluginFeed?": ">=1.4.0"
87-
```
88-
89-
这样，当 `feed` 插件可用时，插件会自动注册自定义的 RSS 源。
90-
91-
## 开发环境
92-
93-
```bash
94-
git clone [email protected]:halo-dev/plugin-feed.git
95-
96-
# 或者当你 fork 之后
97-
98-
git clone [email protected]:{your_github_id}/plugin-feed.git
99-
```
100-
101-
```bash
102-
cd path/to/plugin-feed
103-
```
104-
105-
```bash
106-
# macOS / Linux
107-
./gradlew build
108-
109-
# Windows
110-
./gradlew.bat build
111-
```
112-
113-
修改 Halo 配置文件：
114-
115-
```yaml
116-
halo:
117-
plugin:
118-
runtime-mode: development
119-
classes-directories:
120-
- "build/classes"
121-
- "build/resources"
122-
lib-directories:
123-
- "libs"
124-
fixedPluginPath:
125-
- "/path/to/plugin-feed"
126-
```
127-
128-
## 使用方式
9+
1. 全站订阅：`/feed.xml` 或者 `/rss.xml`
10+
2. 按照分类订阅：`/feed/categories/{slug}.xml`
11+
3. 按照标签订阅文章：`/feed/tags/{name}.xml`
12+
4. 按照作者订阅：`/feed/authors/{name}.xml`
12913

130-
1. 在 [Releases](https://github.com/halo-dev/plugin-feed/releases) 下载最新的 JAR 文件。
131-
2. 在 Halo 后台的插件管理上传 JAR 文件进行安装。
14+
可在插件列表中点击 RSS 插件进入插件设置页面，查看支持的订阅链接列表。
13215

133-
目前提供了以下订阅链接类型：
16+
如果安装并启用了适配此 RSS 插件的其他插件，例如 [瞬间插件](https://www.halo.run/store/apps/app-SnwWDJ) 则会提供更多的订阅链接类型。
13417

135-
1. 全站订阅：`/feed.xml` 或者 `/rss.xml`
136-
2. 按照分类订阅（可以在插件设置中关闭）：`/feed/categories/{slug}.xml`
137-
3. 按照作者订阅（可以在插件设置中关闭）：`/feed/authors/{name}.xml`
18+
你可以将订阅链接添加到 [Feedly](https://feedly.com/)、[Inoreader](https://www.inoreader.com/)、[Reeder](https://reederapp.com/)、[NetNewsWire](https://ranchero.com/netnewswire/)、[Follow](https://follow.is)
19+
等 RSS 订阅工具中，订阅你感兴趣的内容，但需要注意的是，链接中的 `{slug}`、`{name}` 等为占位符，需要替换为实际的类目名称，slug
20+
表示资源别名，name 表示资源唯一标识名。

‎docs/developer.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# 开发文档
2+
3+
> 参考 [Halo 插件开发文档](https://docs.halo.run/developer-guide/plugin/hello-world) 运行插件。
4+
5+
## 如何扩展 RSS 源
6+
7+
> 从 feed 插件 v1.4.0 版本开始，支持扩展 RSS 功能。
8+
9+
`feed` 插件提供了扩展点，允许其他插件扩展 RSS 源。
10+
11+
### 步骤 1：在插件中引入 feed 依赖
12+
13+
在你的插件项目中添加 `feed` 插件的依赖：
14+
15+
```groovy
16+
dependencies {
17+
// ...
18+
compileOnly "run.halo.feed:api:{version}"
19+
}
20+
```
21+
22+
将 `{version}` 替换为实际的 `feed` 插件版本号。
23+
24+
### 步骤 2：实现 `RssRouteItem` 扩展点接口
25+
26+
创建一个类实现 `run.halo.feed.RssRouteItem` 接口，提供自定义的 RSS 数据源。例如：
27+
28+
```java
29+
public class MomentRssProvider implements RssRouteItem {
30+
// 实现具体的 RSS 提供逻辑
31+
}
32+
```
33+
34+
你可以参考 [PostRssProvider](./app/src/main/java/run/halo/feed/provider/PostRssProvider.java) 示例。
35+
36+
### 步骤 3：声明扩展点
37+
38+
在 `src/main/resources/extensions`
39+
目录下，声明你的扩展。你可以参考 [ext-definition.yaml](app/src/main/resources/extensions/ext-definition.yaml) 文件来完成此步骤。
40+
41+
### 步骤 4：定义配置类并清理 RSS 缓存
42+
43+
在插件中定义一个配置类，使用 `@ConditionalOnClass` 注解确保只有在 `run.halo.feed.RssRouteItem` 类存在时才会创建对应的
44+
Bean。同时，定义事件监听器来清理缓存。
45+
46+
`@ConditionalOnClass` 注解只能使用 name 属性来指定类全限定名，不支持使用 value 属性。
47+
48+
示例代码：
49+
50+
```java
51+
52+
@Configuration
53+
@ConditionalOnClass(name = "run.halo.feed.RssRouteItem")
54+
@RequiredArgsConstructor
55+
public class RssAutoConfiguration {
56+
private final ApplicationEventPublisher eventPublisher;
57+
58+
@Bean
59+
public MomentRssProvider momentRssProvider() {
60+
return new MomentRssProvider();
61+
}
62+
63+
@Async
64+
@EventListener({MomentUpdatedEvent.class, MomentDeletedEvent.class})
65+
public void onMomentUpdatedOrDeleted() {
66+
var rule = CacheClearRule.forExact("/feed/moments/rss.xml");
67+
var event = RssCacheClearRequested.forRule(this, rule);
68+
eventPublisher.publishEvent(event);
69+
}
70+
}
71+
```
72+
73+
此配置确保了当 `RssRouteItem` 接口存在时，插件才会自动创建 `MomentRssProvider` 并监听相关事件来清理缓存。
74+
75+
### 步骤 5：声明插件依赖
76+
77+
在 `plugin.yaml` 文件中声明 `feed` 插件为可选依赖，确保当 `feed` 插件存在并启用时，插件能够自动注册 RSS 源。
78+
79+
```yaml
80+
apiVersion: plugin.halo.run/v1alpha1
81+
kind: Plugin
82+
metadata:
83+
name: moment
84+
spec:
85+
pluginDependencies:
86+
"PluginFeed?": ">=1.4.0"
87+
```
88+
89+
这样，当 `feed` 插件可用时，插件会自动注册自定义的 RSS 源。

0 commit comments

Comments
 (0)