RSS Reader

A minimal, fast RSS reader hosted on GitHub Pages with a dark UI.

Features

• Dark mode UI - GitHub-inspired dark theme
• Category tabs - Filter feeds by category
• Collapsible feeds - Click feed headers to expand/collapse
• Inline article expansion - Click articles to read content inline
• Full-text extraction - Fetches complete article content when available
• Read state tracking - Read articles are dimmed (stored in localStorage)
• Keyboard navigation - Use j/k to navigate, / to search, m to mark read
• Search - Filter articles by title in real-time
• Offline support - Service Worker caches feeds for offline reading
• XSS protection - Content sanitized server-side and with DOMPurify
• Parallel fetching - All feeds fetched in parallel for speed
• Content limits - Oversized articles truncated to prevent bloat
• 4-hour updates - GitHub Actions fetches feeds every 4 hours

Live Demo

https://kossov-it.github.io/rss/

Keyboard Shortcuts

Key	Action
j / ↓	Next article
k / ↑	Previous article
Enter / o	Open/close article
m	Mark article as read
/	Focus search
Esc	Close article / blur search

Setup

1. Fork or clone this repo
2. Enable GitHub Pages: Settings → Pages → Source: main branch
3. Enable Actions: Actions → Enable workflows
4. Run the Action manually once: Actions → "Fetch RSS Feeds" → Run workflow
5. Access at https://<username>.github.io/<repo>/

Files

File	Purpose
index.html	Frontend UI (single-page app)
config.json	Feed configuration
scripts/fetch-feeds.js	Feed fetcher (runs in GitHub Action)
.github/workflows/fetch.yml	4-hour cron job
data/feeds-index.json	Lightweight feed index (auto-updated)
data/feeds.json	Legacy full feed data (auto-updated)
data/feeds/*.json	Individual feed files with full content
sw.js	Service Worker for offline support
manifest.json	PWA manifest

Configuration

Edit config.json:

{
  "articlesPerFeed": 20,
  "fetchFullText": true,
  "categories": [
    {
      "name": "News",
      "feeds": [
        { "title": "Feed Name", "url": "https://example.com/rss" }
      ]
    }
  ]
}

Options

Option	Description
articlesPerFeed	Default number of articles per feed
fetchFullText	Enable full article content extraction
Per-feed articlesPerFeed	Override default for specific feeds

Push changes and the Action will run automatically.

Local Development

# Install dependencies
npm install

# Fetch feeds locally
node scripts/fetch-feeds.js

# Serve locally (required - can't open index.html directly due to CORS)
python3 -m http.server 8000
# Then open http://localhost:8000

Architecture

Data Flow

1. GitHub Action runs every 4 hours
2. fetch-feeds.js fetches all RSS feeds in parallel
3. For each article, extracts full content using Readability
4. Sanitizes content server-side (removes scripts, event handlers)
5. Truncates oversized content (>50KB) to prevent bloat
6. Writes lightweight index + individual feed files

Frontend

• Loads lightweight index first (feeds-index.json)
• Lazy-loads full article content on click
• Falls back to legacy feeds.json if index unavailable
• Caches loaded content in memory

Notes

• Read state stored in browser localStorage (not synced across devices)
• Unique IDs prefixed with feed slug to prevent collisions
• Content size limit of 50KB prevents bloated "Top 10" listicles
• Honest user-agent identifies as RSSReader to avoid ToS violations
• Health checks fail the build if no articles were fetched