Managing Feed Configs

For easier management, especially when using the CLI or html2rss-web, you can store your feed configurations in a YAML file.

Global and Feed-Specific Configurations

You can define global settings that apply to all feeds, and then define individual feed configurations under the feeds key.

# Global settings
headers:
  "User-Agent": "Mozilla/5.0 (compatible; html2rss/1.0; Mobile)"
  "Accept": "text/html"

# Feed-specific settings
feeds:
  my-first-feed:
    channel:
      url: "https://example.com/blog"
    selectors:
      items:
        selector: ".post"
      title:
        selector: "h2"
      url:
        selector: "a"
        extractor: "href"
  my-second-feed:
    channel:
      url: "https://example.com/news"
    selectors:
      items:
        selector: ".news-item"
      title:
        selector: "h2"
      url:
        selector: "a"
        extractor: "href"

Building Feeds from a YAML File

Ruby

require 'html2rss'
# Build a specific feed from the YAML file
my_feed_config = Html2rss.config_from_yaml_file('feeds.yml', 'my-first-feed')
rss = Html2rss.feed(my_feed_config)
puts rss
# If the YAML file contains only one feed, you can omit the feed name
single_feed_config = Html2rss.config_from_yaml_file('single.yml')
rss = Html2rss.feed(single_feed_config)
puts rss

Ruby API: FeedResult

Prefer Html2rss.feed_result when one scrape must render as both RSS and JSON Feed, or when you Marshal-cache the scrape and render later. Html2rss.feed and Html2rss.json_feed remain convenience wrappers over the same path.

FeedResult is an opaque handle. Public surface:

• empty? — whether the scrape produced items
• channel_title — channel title string only
• to_rss / to_json_feed(feed_url:) — render formats
• status — scrape telemetry (Html2rss::Status)

status.to_h is the stable observability payload. Always includes version and dedup_dropped. When present, it may also include scraper_tallies, selected_strategy, attempt_count, strategy_attempts (auto-fallback attempts; empty outside strategy: auto), and admission_drops (Cleanup reason → count).

For URL-only auto discovery, Html2rss.auto_feed_result(url) returns the same FeedResult (CLI html2rss auto --explain prints status.to_h on stderr).

require 'html2rss'
config = Html2rss.config_from_yaml_file('feeds.yml', 'my-first-feed')
result = Html2rss.feed_result(config)
result.to_rss
result.to_json_feed(feed_url: 'https://example.com/feeds/my-first-feed.json')
result.status.to_h
# => { version: "...", dedup_dropped: 0, selected_strategy: :botasaurus, ... }

Depth and method contracts: YARD for html2rss.

Command Line

html2rss feed feeds.yml my-first-feed ; html2rss feed single.yml