🎯 Vibe Coding Project: This project is developed in a freeform, experimental, and improvisational style.
⚠️ No pull requests will be honored. If you have a feature request or bug, please open an issue and I'll vibe code it (maybe it works, maybe not). Thanks for understanding!

StupidRSS

v0.0.1 - Keep it simple, keep it fast, keep it stupid

A fast, minimalistic RSS reader built with FastAPI and Tailwind CSS. No bloat, just pure RSS reading experience with a modern dark/light interface.

Get Started View Code
New

Version 0.0.1 Released

Our first official release with major mobile UI improvements

What's New

  • Enhanced mobile filtering with improved touch targets
  • Standardized button widths for consistent UI
  • Responsive admin interface optimized for mobile devices
  • "Made with ❤️ in Michigan" footer across all pages
View full release notes

Features

Everything you need for RSS reading, nothing you don't

Lightning Fast

Built with FastAPI for maximum performance and async RSS parsing

Dark Mode

Beautiful dark/light theme with system preference detection

REST API

Full REST API with auto-generated OpenAPI documentation

Minimalistic

Clean interface focused on reading, no unnecessary features

Responsive

Works perfectly on desktop, tablet, and mobile devices

SQLite Database

Lightweight, zero-config database for storing feeds and articles

Smart Content Cleaning

Automatically strips HTML while preserving formatting and lists

YouTube Optimized

Removes spam and duplicate content from video feeds

Enhanced UX

Streamlined buttons, improved navigation, and consistent UI

Category Organization

Organize feeds by categories with dedicated pages and filtering

Advanced Filtering

Filter by All, Unread, and Saved across all pages and categories

Intuitive Navigation

Smart sidebar navigation and clean header design across all pages

Recent Improvements

Latest enhancements to make your RSS reading experience even better

✨ Content Processing

  • • HTML tag removal with formatting preservation
  • • Automatic list formatting (bullets & numbering)
  • • YouTube spam and promotional content removal
  • • Duplicate description elimination
  • • HTML entity conversion to readable text

🎯 User Experience

  • • Standardized "Add Feed" and "Delete" buttons
  • • Enhanced delete confirmation (type "DELETE")
  • • Streamlined feed display on home page
  • • Working filter buttons for article management
  • • Consistent UI styling across all pages

📂 Category Management

  • • Organize feeds into customizable categories
  • • Dedicated category overview and detail pages
  • • Advanced filtering (All, Unread, Saved)
  • • Intuitive sidebar navigation structure
  • • Clean article previews with expand options

Tech Stack

Modern technologies for maximum performance

Backend

  • • FastAPI - Modern async Python web framework
  • • SQLAlchemy - Python SQL toolkit and ORM
  • • SQLite - Lightweight database
  • • feedparser - RSS/Atom feed parsing
  • • httpx - Async HTTP client

Frontend

  • • Jinja2 - Template engine
  • • Tailwind CSS - Utility-first CSS framework
  • • Vanilla JavaScript - No heavy frameworks
  • • Dark Mode - System preference aware
  • • Responsive Design - Mobile-first approach

Screenshots

See StupidRSS in action

Main Page - Feed Overview

StupidRSS Main Page showing feed overview and recent articles

Clean, minimal interface showing all your feeds and recent articles

Article Reading Experience

StupidRSS Article page with clean content display

HTML-cleaned content with preserved formatting for optimal reading

Admin Panel - Feed Management

StupidRSS Admin panel for managing feeds

Easy feed management with enhanced delete confirmation

Saved Articles

StupidRSS Saved articles page

Keep track of your favorite articles with the save functionality

API Documentation

REST API endpoints for programmatic access

Feeds

GET /api/feeds
GET /api/feeds/{id}
PUT /api/feeds/{id}
DEL /feeds/{id}

Articles

GET /api/articles
GET /api/feeds/{id}/articles
POST /feeds/{id}/refresh
POST /api/articles/{id}/read

Quick Start

Get StupidRSS running in minutes

# Clone the repository
git clone https://github.com/dannycab/stupidrss.git
cd stupidrss

# Install dependencies
pip install -r requirements.txt

# Run the application
python main.py

# Open your browser to the RSS reader
open http://localhost:8000/

# Or run with Docker
docker-compose up -d

🐳 Docker Setup

The easiest way to run StupidRSS is with Docker Compose. Customize your deployment with environment variables:

# Copy and customize environment variables (optional) cp .env.example .env # Start the application docker-compose up -d

This will start the app on http://localhost:8000 with persistent data storage.

Environment Variables

PORT 8000
DATA_VOLUME_PATH ./data
DATABASE_URL sqlite:///data/rss_reader.db

The .env file is not committed to the repository, allowing secure customization.