This README is the one indexed from the repository at its latest ref, not from the tag for this version.

Planeta

A modern, high-performance blog aggregator written in Crystal that aggregates posts from multiple ATOM and RSS feeds.

Features

• Concurrent Feed Processing: Fetches multiple feeds simultaneously using Crystal fibers
• Multi-format Support: Parses both ATOM and RSS feed formats
• Intelligent Caching: File-based caching with configurable duration and statistics
• Advanced Search: Filter posts by title, summary, or author
• Pagination: Efficient handling of large entry sets with clean navigation
• Security: Input validation, HTML sanitization, and safe XML parsing
• Performance: Optimized memory usage and pre-allocated data structures
• Responsive Design: Clean, minimalist UI with dark/light theme support
• Internationalization: Supports English and Spanish with browser language detection
• Error Handling: Robust error recovery and logging
• Developer Tools: Comprehensive test suite, linting, and code analysis tools

Installation

Prerequisites

• Crystal 1.19.1 or later
• Git

Build

git clone <repository-url>
cd planeta
shards install
crystal build src/planeta.cr

Usage

1. Edit urls.txt to add your feed URLs (one per line)
2. Run the application: ./planeta or crystal run src/planeta.cr
3. Open http://localhost:3000 in your browser

The application supports concurrent feed fetching, so adding more feeds won't significantly impact performance.

Command Line Options

Planeta supports various command line options:

./planeta --help

Available options:

• -h, --help: Show help message
• -v, --version: Show version information
• -p PORT, --port PORT: Specify port (default: 3000)
• --host HOST: Specify host (default: 127.0.0.1)
• -u FILE, --urls-file FILE: Specify URLs file (default: urls.txt)
• -c DIR, --cache-dir DIR: Specify cache directory (default: ./cache)
• -l LEVEL, --log-level LEVEL: Specify log level (default: info)

Web Interface Features

• Search: Filter posts by entering keywords in the search box
• Pagination: Navigate through large numbers of posts (10 per page by default, max 50)
• Theme Toggle: Switch between dark and light themes
• Locale Toggle: Switch between English and Spanish (click the locale button in the header)
• Responsive Design: Works on desktop and mobile devices

Internationalization (i18n)

Planeta supports English and Spanish. Translations are stored in i18n/*.yaml files.

• Browser Detection: Automatically detects your preferred language from the browser's Accept-Language header
• Manual Toggle: Click the locale button (EN/ES) in the header to switch languages
• Query Parameter: Use ?locale=es or ?locale=en to force a specific language
• Cookie Persistence: Language preference is stored in a cookie for 1 year
• Environment Variable: Set PLANETA_LOCALE env var to set default language

Examples:

./planeta --port 8080
./planeta --urls-file myfeeds.txt --cache-dir /tmp/cache
PLANETA_LOG_LEVEL=debug ./planeta

Configuration

• Feed URLs: Add URLs to urls.txt, one per line (or set PLANETA_URLS_FILE env var)
• Cache Duration: Set PLANETA_CACHE_DURATION_MINUTES env var (default: 15 minutes)
• Cache Directory: Set PLANETA_CACHE_DIR env var (default: ./cache)
• Log Level: Set PLANETA_LOG_LEVEL env var (default: info)

Example urls.txt

https://blog.example.com/feed/
https://another-blog.com/atom.xml
https://rss-feed.com/rss

Development

Running in development

crystal run src/planeta.cr

Testing

crystal spec

Building

# Standard build
make build

# Release build with preview_mt
make release

# Static build (no runtime dependencies)
make container-build
./bin/planeta-static

Architecture

• Feed Parsing: Handles both ATOM and RSS formats using Crystal's XML library
• Caching: File-based caching to avoid repeated fetches
• Aggregation: Collects entries from all feeds and sorts by date
• Rendering: Uses Slang templates for clean HTML output

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

License

GPL-3.0-or-later

Contributors

• Rénich Bon Ćirić - creator and maintainer