64 lines
2.7 KiB
Markdown
64 lines
2.7 KiB
Markdown
# FreshRSS List Widget for Homepage
|
|
|
|
A custom widget for [gethomepage.dev](https://gethomepage.dev) that displays the latest RSS feed items from your [FreshRSS](https://freshrss.org/) subscriptions.
|
|
|
|
## Why?
|
|
|
|
The built-in FreshRSS widget for Homepage only shows the **unread count**. This widget goes a step further by listing the actual articles from your reading list (or a specific category) directly on your dashboard.
|
|
|
|
## Features
|
|
|
|
- Lists recent RSS items with title, date, author, and source feed.
|
|
- Supports filtering by FreshRSS category/label.
|
|
- Configurable number of items to display.
|
|
- Links directly to the article.
|
|
|
|
## Prerequisites
|
|
|
|
- A running FreshRSS instance with the **Google Reader API** enabled.
|
|
- In FreshRSS: **Settings → Profile → API management** → Enable API and set your API password.
|
|
- Ensure the Google Reader API endpoint (`api/greader.php`) is accessible.
|
|
|
|
## Installation
|
|
|
|
1. Copy the `freshrsslist` folder into your Homepage widgets directory (e.g., `src/widgets/` or your custom widgets path).
|
|
2. If Homepage requires widget registration, import and add it to your widget registry.
|
|
|
|
## Configuration
|
|
|
|
Add the widget to your `services.yaml` (or `widgets.yaml`):
|
|
|
|
```yaml
|
|
- FreshRSS:
|
|
href: https://your-freshrss-instance.com
|
|
widget:
|
|
type: freshrsslist
|
|
url: https://your-freshrss-instance.com
|
|
username: your_username
|
|
password: your_api_password # Not your regular login password
|
|
category: Tech # Optional: filter by FreshRSS label
|
|
limit: 5 # Optional: number of items (default: 5)
|
|
```
|
|
|
|
## Options
|
|
| Field | Required | Description |
|
|
|------------|----------|------------------------------------------------------------------------|
|
|
| `url` | Yes | Base URL of your FreshRSS instance. |
|
|
| `username` | Yes | Your FreshRSS username. |
|
|
| `password` | Yes | Your FreshRSS **API password** (set in Profile → API management). |
|
|
| `category` | No | A FreshRSS category/label to filter items. Omit to show reading list. |
|
|
| `limit` | No | Number of items to display. Default: `5`. |
|
|
|
|
## How It Works
|
|
|
|
The widget authenticates with FreshRSS via the Google Reader API (`ClientLogin`) and fetches the stream contents. It then maps the API response to a clean list of articles rendered inside a Homepage service container.
|
|
|
|
## File Structure
|
|
|
|
- `widget.js` — Defines the widget endpoint and proxy handler.
|
|
- `proxy.js` — Handles FreshRSS authentication and API requests.
|
|
- `components.jsx` — The React component that renders the RSS list.
|
|
|
|
## License
|
|
MIT
|