html2rss 0.17.0 → 0.18.0

data/README.md

@@ -1,686 +1,78 @@
 ![html2rss logo](https://github.com/html2rss/html2rss/raw/master/support/logo.png)
 
-[![Gem Version](https://badge.fury.io/rb/html2rss.svg)](http://rubygems.org/gems/html2rss/) [![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://www.rubydoc.info/gems/html2rss) ![Retro Badge: valid RSS](https://validator.w3.org/feed/images/valid-rss-rogers.png)
+[![Gem Version](https://badge.fury.io/rb/html2rss.svg)](http://rubygems.org/gems/html2rss) [![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://www.rubydoc.info/gems/html2rss) ![Retro Badge: valid RSS](https://validator.w3.org/feed/images/valid-rss-rogers.png) [![CI](https://github.com/html2rss/html2rss/workflows/lint%20and%20test/badge.svg)](https://github.com/html2rss/html2rss/actions)
 
-`html2rss` is a Ruby gem that generates RSS 2.0 feeds from websites automatically, and as a fallback via _feed config_.
+`html2rss` is a Ruby gem that generates RSS 2.0 feeds from websites by scraping HTML or JSON content with **CSS selectors** or **auto-detection**.
 
-With the _feed config_, you provide a URL to scrape and CSS selectors for extracting information (like title, URL, etc.). The gem builds the RSS feed accordingly. [Extractors](#using-extractors) and chainable [post processors](#using-post-processors) make information extraction, processing, and sanitizing a breeze. The gem also supports [scraping JSON](#scraping-and-handling-json-responses) responses and [setting HTTP request headers](#set-any-http-header-in-the-request).
+This gem is the core of the [html2rss-web](https://github.com/html2rss/html2rss-web) application.
 
-**Looking for a ready-to-use app to serve generated feeds via HTTP?** [Check out `html2rss-web`](https://github.com/html2rss/html2rss-web)!
+Most people looking for a first working feed should start with `html2rss-web`, run it with Docker, and open one of the included feeds from their own instance before moving to custom configs or the gem APIs.
 
-Support the development by sponsoring this project on GitHub. Thank you! 💓
+## Documentation
 
-## Generating a feed on the CLI
+Detailed usage guides, reference docs, and the feed directory live on the project website:
 
-[Install Ruby](https://www.ruby-lang.org/en/documentation/installation/) (latest version is recommended) on your machine and run `gem install html2rss` in your terminal.
+- [Ruby gem documentation](https://html2rss.github.io/ruby-gem)
+- [Web application](https://html2rss.github.io/web-application)
+- [Feed directory](https://html2rss.github.io/feed-directory)
+- [Contributing guide](https://html2rss.github.io/get-involved/contributing)
+- [GitHub Discussions](https://github.com/orgs/html2rss/discussions)
+- [Sponsor on GitHub](https://github.com/sponsors/gildesmarais)
 
-After the installation has finished, `html2rss help` will print usage information.
+### 💻 Try in Browser
 
-### using automatic generation
+You can develop html2rss directly in your browser using GitHub Codespaces:
 
-html2rss offers an automatic RSS generation feature. Try it with:
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?repo=html2rss/html2rss)
 
-`html2rss auto https://unmatchedstyle.com/`
+The Codespace comes pre-configured with Ruby 3.4 (compatible with Ruby 4.0), all dependencies, and VS Code extensions ready to go!
 
-### creating a feed config file and using it
+## 🤝 Contributing
 
-If the results are not to your satisfaction, you can create a feed config file.
+Please see the [contributing guide](https://html2rss.github.io/get-involved/contributing) for details on how to contribute.
 
-Create a file called `my_config_file.yml` with this sample content:
+## 🏗️ Architecture
 
-```yml
-channel:
-  url: https://unmatchedstyle.com
-selectors:
-  items:
-    selector: "article[id^='post-']"
-  title:
-    selector: h2
-  link:
-    selector: a
-    extractor: href
-  description:
-    selector: ".post-content"
-    post_process:
-      - name: sanitize_html
-```
-
-Build the feed from this config with: `html2rss feed ./my_config_file.yml`.
-
-## Generating a feed with Ruby
-
-You can also install it as a dependency in your Ruby project:
-
-|                      🤩 Like it? | Star it! ⭐️         |
-| -------------------------------: | -------------------- |
-| Add this line to your `Gemfile`: | `gem 'html2rss'`     |
-|                    Then execute: | `bundle`             |
-|                    In your code: | `require 'html2rss'` |
-
-Here's a minimal working example using Ruby:
+### Core Components
 
-```ruby
-require 'html2rss'
+1. **Config** - Loads and validates configuration (YAML/hash)
+2. **RequestService** - Fetches pages using Faraday or Browserless
+3. **Selectors** - Extracts content via CSS selectors with extractors/post-processors
+4. **AutoSource** - Auto-detects content using Schema.org, JSON state blobs, semantic HTML, and structural patterns
+5. **RssBuilder** - Assembles Article objects and renders RSS 2.0
 
-rss =
-  Html2rss.feed(
-    channel: { url: 'https://stackoverflow.com/questions' },
-    selectors: {
-      items: { selector: '#hot-network-questions > ul > li' },
-      title: { selector: 'a' },
-      link: { selector: 'a', extractor: 'href' }
-    }
-  )
+### Data Flow
 
-puts rss
+```text
+Config -> Request -> Extraction -> Processing -> Building -> Output
 ```
 
-## The _feed config_ and its options
-
-A _feed config_ consists of a `channel` and a `selectors` hash. The contents of both hashes are explained below.
-
-Good to know:
-
-- You'll find extensive example feed configs at [`spec/*.test.yml`](https://github.com/html2rss/html2rss/tree/master/spec).
-- See [`html2rss-configs`](https://github.com/html2rss/html2rss-configs) for ready-made feed configs!
-- If you've created feed configs, you're invited to send a PR to [`html2rss-configs`](https://github.com/html2rss/html2rss-configs) to make your config available to the public.
-
-Alright, let's move on.
-
-### The `channel`
-
-| attribute     |              | type    | default        | remark                                     |
-| ------------- | ------------ | ------- | -------------- | ------------------------------------------ |
-| `url`         | **required** | String  |                |                                            |
-| `title`       | optional     | String  | auto-generated |                                            |
-| `description` | optional     | String  | auto-generated |                                            |
-| `ttl`         | optional     | Integer | `360`          | TTL in _minutes_                           |
-| `time_zone`   | optional     | String  | `'UTC'`        | TimeZone name                              |
-| `language`    | optional     | String  | `'en'`         | Language code                              |
-| `author`      | optional     | String  |                | Format: `email (Name)`                     |
-| `headers`     | optional     | Hash    | `{}`           | Set HTTP request headers. See notes below. |
-| `json`        | optional     | Boolean | `false`        | Handle JSON response. See notes below.     |
-
-#### Dynamic parameters in `channel` attributes
-
-Sometimes there are structurally similar pages with different URLs. In such cases, you can add _dynamic parameters_ to the channel's attributes.
-
-Example of a dynamic `id` parameter in the channel URLs:
-
-```yml
-channel:
-  url: "http://domainname.tld/whatever/%<id>s.html"
-```
-
-Command line usage example:
-
-```sh
-html2rss feed the_feed_config.yml id=42
-```
-
-<details><summary>See a Ruby example</summary>
-
-```ruby
-config = Html2rss::Config.new({ channel: { url: 'http://domainname.tld/whatever/%<id>s.html' } }, {}, { id: 42 })
-Html2rss.feed(config)
-```
-
-</details>
-
-See the more complex formatting options of the [`sprintf` method](https://ruby-doc.org/core/Kernel.html#method-i-sprintf).
-
-### The `selectors`
-
-First, you must give an **`items`** selector hash, which contains a CSS selector. The selector selects a collection of HTML tags from which the RSS feed items are built. Except for the `items` selector, all other keys are scoped to each item of the collection.
-
-To build a [valid RSS 2.0 item](http://www.rssboard.org/rss-profile#element-channel-item), you need at least a `title` **or** a `description`. You can have both.
-
-Having an `items` and a `title` selector is enough to build a simple feed.
-
-Your `selectors` hash can contain arbitrary named selectors, but only a few will make it into the RSS feed (due to the RSS 2.0 specification):
-
-| RSS 2.0 tag   | name in `html2rss` | remark                                      |
-| ------------- | ------------------ | ------------------------------------------- |
-| `title`       | `title`            |                                             |
-| `description` | `description`      | Supports HTML.                              |
-| `link`        | `link`             | A URL.                                      |
-| `author`      | `author`           |                                             |
-| `category`    | `categories`       | See notes below.                            |
-| `guid`        | `guid`             | Default title/description. See notes below. |
-| `enclosure`   | `enclosure`        | See notes below.                            |
-| `pubDate`     | `updated`          | An instance of `Time`.                      |
-| `comments`    | `comments`         | A URL.                                      |
-| `source`      | ~~source~~         | Not yet supported.                          |
-
-### Build RSS 2.0 item attributes by specifying selectors
-
-Every named selector (i.e. `title`, `description`, see table above) in your `selectors` hash can have these attributes:
-
-| name           | value                                                    |
-| -------------- | -------------------------------------------------------- |
-| `selector`     | The CSS selector to select the tag with the information. |
-| `extractor`    | Name of the extractor. See notes below.                  |
-| `post_process` | A hash or array of hashes. See notes below.              |
-
-#### Using extractors
-
-Extractors help with extracting the information from the selected HTML tag.
-
-- The default extractor is `text`, which returns the tag's inner text.
-- The `html` extractor returns the tag's outer HTML.
-- The `href` extractor returns a URL from the tag's `href` attribute and corrects relative ones to absolute ones.
-- The `attribute` extractor returns the value of that tag's attribute.
-- The `static` extractor returns the configured static value (it doesn't extract anything).
-- [See file list of extractors](https://github.com/html2rss/html2rss/tree/master/lib/html2rss/item_extractors).
-
-Extractors might need extra attributes on the selector hash. 👉 [Read their docs for usage examples](https://www.rubydoc.info/gems/html2rss/Html2rss/ItemExtractors).
-
-<details><summary>See a Ruby example</summary>
-
-```ruby
-Html2rss.feed(
-  channel: {}, selectors: { link: { selector: 'a', extractor: 'href' } }
-)
-```
-
-</details>
-
-<details><summary>See a YAML feed config example</summary>
-
-```yml
-channel:
-  # ... omitted
-selectors:
-  # ... omitted
-  link:
-    selector: "a"
-    extractor: "href"
-```
-
-</details>
-
-### Using post processors
-
-Extracted information can be further manipulated with post processors.
-
-| name               |                                                                                       |
-| ------------------ | ------------------------------------------------------------------------------------- |
-| `gsub`             | Allows global substitution operations on Strings (Regexp or simple pattern).          |
-| `html_to_markdown` | HTML to Markdown, using [reverse_markdown](https://github.com/xijo/reverse_markdown). |
-| `markdown_to_html` | converts Markdown to HTML, using [kramdown](https://github.com/gettalong/kramdown).   |
-| `parse_time`       | Parses a String containing a time in a time zone.                                     |
-| `parse_uri`        | Parses a String as URL.                                                               |
-| `sanitize_html`    | Strips unsafe and uneeded HTML and adds security related attributes.                  |
-| `substring`        | Cuts a part off of a String, starting at a position.                                  |
-| `template`         | Based on a template, it creates a new String filled with other selectors values.      |
-
-⚠️ Always make use of the `sanitize_html` post processor for HTML content. _Never trust the internet!_ ⚠️
-
-#### Chaining post processors
-
-Pass an array to `post_process` to chain the post processors.
-
-<details><summary>YAML example: build the description from a template String (in Markdown) and convert that Markdown to HTML</summary>
-
-```yml
-channel:
-  # ... omitted
-selectors:
-  # ... omitted
-  price:
-    selector: '.price'
-  description:
-    selector: '.section'
-    post_process:
-      - name: template
-        string: |
-          # %{self}
-
-          Price: %{price}
-      - name: markdown_to_html
-```
-
-</details>
-
-##### Post processor `gsub`
-
-The post processor `gsub` makes use of Ruby's [`gsub`](https://apidock.com/ruby/String/gsub) method.
-
-| key           | type   | required | note                     |
-| ------------- | ------ | -------- | ------------------------ |
-| `pattern`     | String | yes      | Can be Regexp or String. |
-| `replacement` | String | yes      | Can be a backreference.  |
-
-<details><summary>See a Ruby example</summary>
-
-```ruby
-Html2rss.feed(
-  channel: {},
-  selectors: {
-    title: { selector: 'a', post_process: [{ name: 'gsub', pattern: 'foo', replacement: 'bar' }] }
-  }
-)
-```
-
-</details>
-
-<details><summary>See a YAML feed config example</summary>
-
-```yml
-channel:
-  # ... omitted
-selectors:
-  # ... omitted
-  title:
-    selector: "a"
-    post_process:
-      - name: "gsub"
-        pattern: "foo"
-        replacement: "bar"
-```
-
-</details>
-
-#### Adding `<category>` tags to an item
-
-The `categories` selector takes an array of selector names. Each value of those
-selectors will become a `<category>` on the RSS item.
-
-<details>
-  <summary>See a Ruby example</summary>
-
-```ruby
-Html2rss.feed(
-  channel: {},
-  selectors: {
-    genre: {
-      # ... omitted
-      selector: '.genre'
-    },
-    branch: { selector: '.branch' },
-    categories: %i[genre branch]
-  }
-)
-```
-
-</details>
-
-<details>
-  <summary>See a YAML feed config example</summary>
-
-```yml
-channel:
-  # ... omitted
-selectors:
-  # ... omitted
-  genre:
-    selector: ".genre"
-  branch:
-    selector: ".branch"
-  categories:
-    - genre
-    - branch
-```
-
-</details>
-
-#### Custom item GUID
-
-By default, html2rss generates a GUID from the `title` or `description`.
-
-If this does not work well, you can choose other attributes from which the GUID is build.
-The principle is the same as for the categories: pass an array of selectors names.
-
-In all cases, the GUID is a SHA1-encoded string.
-
-<details><summary>See a Ruby example</summary>
-
-```ruby
-Html2rss.feed(
-  channel: {},
-  selectors: {
-    title: {
-      # ... omitted
-      selector: 'h1'
-    },
-    link: { selector: 'a', extractor: 'href' },
-    guid: %i[link]
-  }
-)
-```
-
-</details>
-
-<details><summary>See a YAML feed config example</summary>
-
-```yml
-channel:
-  # ... omitted
-selectors:
-  # ... omitted
-  title:
-    selector: "h1"
-  link:
-    selector: "a"
-    extractor: "href"
-  guid:
-    - link
-```
-
-</details>
-
-#### Adding an `<enclosure>` tag to an item
-
-An enclosure can be any file, e.g. a image, audio or video - think Podcast.
-
-The `enclosure` selector needs to return a URL of the content to enclose. If the extracted URL is relative, it will be converted to an absolute one using the channel's URL as base.
-
-Since `html2rss` does no further inspection of the enclosure, its support comes with trade-offs:
-
-1. The content-type is guessed from the file extension of the URL, unless one is specified in `content_type`.
-2. If the content-type guessing fails, it will default to `application/octet-stream`.
-3. The content-length will always be undetermined and therefore stated as `0` bytes.
-
-Read the [RSS 2.0 spec](http://www.rssboard.org/rss-profile#element-channel-item-enclosure) for further information on enclosing content.
-
-<details>
-  <summary>See a Ruby example</summary>
-
-```ruby
-Html2rss.feed(
-  channel: {},
-  selectors: {
-    enclosure: {
-      selector: 'audio',
-      extractor: 'attribute',
-      attribute: 'src',
-      content_type: 'audio/mp3'
-    }
-  }
-)
-```
-
-</details>
-
-<details>
-  <summary>See a YAML feed config example</summary>
-
-```yml
-channel:
-  # ... omitted
-selectors:
-  # ... omitted
-  enclosure:
-    selector: "audio"
-    extractor: "attribute"
-    attribute: "src"
-    content_type: "audio/mp3"
-```
-
-</details>
-
-## Scraping and handling JSON responses
-
-By default, `html2rss` assumes the URL responds with HTML. However, it can also handle JSON responses. The JSON response must be an Array or Hash.
-
-The JSON is converted to XML which you can query using CSS selectors.
-
-<details><summary>See a Ruby example</summary>
-
-```ruby
-Html2rss.feed(
-  channel: { url: 'http://domainname.tld/whatever.json', json: true },
-  selectors: { title: { selector: 'foo' } }
-)
-```
-
-</details>
-
-<details><summary>See a YAML feed config example</summary>
-
-```yml
-channel:
-  url: "http://domainname.tld/whatever.json"
-  json: true
-selectors:
-  title:
-    selector: "foo"
-```
-
-</details>
-
-## Customization of how requests to the channel URL are sent
-
-By default, html2rss issues a naiive HTTP request and extracts information from the response. That is performant and works for many websites.
-
-However, modern websites often do not render much HTML on the server, but evaluate JavaScript on the client to create the HTML. In such cases, the default strategy will not find the "juicy content".
-
-### Use Browserless.io
-
-You can use _Browserless.io_ to run a Chrome browser and return the website's source code after the website generated it.
-For this, you can either run your own Browserless.io instance (Docker image available -- [read their license](https://github.com/browserless/browserless/pkgs/container/chromium#licensing)!) or pay them for a hosted instance.
-
-To run a local Browserless.io instance, you can use the following Docker command:
-
-```sh
-docker run \
-  --rm \
-  -p 3000:3000 \
-  -e "CONCURRENT=10" \
-  -e "TOKEN=6R0W53R135510" \
-  ghcr.io/browserless/chromium
-```
-
-To make html2rss use your instance,
-
-1. specify the environment variables accordingly, and
-2. use the `browserless` strategy for those websites.
-
-When running locally with commands from above, you can skip setting the environment variables, as they are aligned with the default values.
-
-```sh
-BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000" BROWSERLESS_IO_API_TOKEN="6R0W53R135510" \
-  html2rss auto --strategy=browserless https://example.com
-```
-
-When using traditional feed configs, inside your channel config set `strategy: browserless`.
-
-<details><summary>See a YAML feed config example</summary>
-
-```yml
-channel:
-  url: https://www.imdb.com/user/ur67728460/ratings
-  time_zone: UTC
-  ttl: 1440
-  strategy: browserless
-  headers:
-    User-Agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
-selectors:
-  items:
-    selector: "li.ipc-metadata-list-summary-item"
-  title:
-    selector: ".ipc-title__text"
-    post_process:
-      - name: gsub
-        pattern: "/^(\\d+.)\\s/"
-        replacement: ""
-      - name: template
-        string: "%{self} rated with: %{user_rating}"
-  link:
-    selector: "a.ipc-title-link-wrapper"
-    extractor: "href"
-  user_rating:
-    selector: "[data-testid='ratingGroup--other-user-rating'] > .ipc-rating-star--rating"
-```
-
-</details>
-
-### Set any HTTP header in the request
-
-To set HTTP request headers, you can add them to the channel's `headers` hash. This is useful for APIs that require an Authorization header.
-
-```yml
-channel:
-  url: "https://example.com/api/resource"
-  headers:
-    Authorization: "Bearer YOUR_TOKEN"
-selectors:
-  # ... omitted
-```
-
-Or for setting a User-Agent:
-
-```yml
-channel:
-  url: "https://example.com"
-  headers:
-    User-Agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
-selectors:
-  # ... omitted
-```
-
-## Usage with a YAML config file
-
-This step is not required to work with this gem. If you're using
-[`html2rss-web`](https://github.com/html2rss/html2rss-web)
-and want to create your private feed configs, keep on reading!
-
-First, create a YAML file, e.g. `feeds.yml`. This file will contain your global config and multiple feed configs under the key `feeds`.
-
-Example:
-
-```yml
-headers:
-  "User-Agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_1 like Mac OS X) AppleWebKit/603.1.30 (KHTML, like Gecko) Version/10.0 Mobile/14E304 Safari/602.1"
-feeds:
-  myfeed:
-    channel:
-    selectors:
-  myotherfeed:
-    channel:
-    selectors:
-```
-
-Your feed configs go below `feeds`. Everything else is part of the global config.
-
-Find a full example of a `feeds.yml` at [`spec/fixtures/feeds.test.yml`](https://github.com/html2rss/html2rss/blob/master/spec/fixtures/feeds.test.yml).
-
-Now you can build your feeds like this:
-
-<details>
-  <summary>Build feeds in Ruby</summary>
-
-```ruby
-require 'html2rss'
-
-myfeed = Html2rss.feed_from_yaml_config('feeds.yml', 'myfeed')
-myotherfeed = Html2rss.feed_from_yaml_config('feeds.yml', 'myotherfeed')
-```
-
-</details>
-
-<details>
-  <summary>Build feeds on the command line</summary>
-
-```sh
-html2rss feed feeds.yml myfeed
-html2rss feed feeds.yml myotherfeed
-```
-
-</details>
-
-## Display the RSS feed nicely in a web browser
-
-To display RSS feeds nicely in a web browser, you can:
-
-- add a plain old CSS stylesheet, or
-- use XSLT (e**X**tensible **S**tylesheet **L**anguage **T**ransformations).
-
-A web browser will apply these stylesheets and show the contents as described.
-
-In a CSS stylesheet, you'd use `element` selectors to apply styles.
-
-If you want to do more, then you need to create a XSLT. XSLT allows you
-to use a HTML template and to freely design the information of the RSS,
-including using JavaScript and external resources.
-
-You can add as many stylesheets and types as you like. Just add them to your global configuration.
-
-<details>
-  <summary>Ruby: a stylesheet config example</summary>
-
-```ruby
-config = Html2rss::Config.new(
-  { channel: {}, selectors: {} }, # omitted
-  {
-    stylesheets: [
-      {
-        href: '/relative/base/path/to/style.xls',
-        media: :all,
-        type: 'text/xsl'
-      },
-      {
-        href: 'http://example.com/rss.css',
-        media: :all,
-        type: 'text/css'
-      }
-    ]
-  }
-)
-
-Html2rss.feed(config)
-```
-
-</details>
-
-<details>
-  <summary>YAML: a stylesheet config example</summary>
-
-```yml
-stylesheets:
-  - href: "/relative/base/path/to/style.xls"
-    media: "all"
-    type: "text/xsl"
-  - href: "http://example.com/rss.css"
-    media: "all"
-    type: "text/css"
-feeds:
-  # ... omitted
-```
-
-</details>
-
-Recommended further readings:
-
-- [How to format RSS with CSS on lifewire.com](https://www.lifewire.com/how-to-format-rss-3469302)
-- [XSLT: Extensible Stylesheet Language Transformations on MDN](https://developer.mozilla.org/en-US/docs/Web/XSLT)
-- [The XSLT used by html2rss-web](https://github.com/html2rss/html2rss-web/blob/master/public/rss.xsl)
-
-## Gotchas and tips & tricks
+### Config schema workflow
 
-- Check that the channel URL does not redirect to a mobile page with a different markup structure.
-- Do not rely on your web browser's developer console. `html2rss` does not execute JavaScript.
-- Fiddling with [`curl`](https://github.com/curl/curl) and [`pup`](https://github.com/ericchiang/pup) to find the selectors seems efficient (`curl URL | pup`).
-- [CSS selectors are versatile. Here's an overview.](https://www.w3.org/TR/selectors-4/#overview)
+The config schema is generated from the runtime `dry-validation` contracts and exported for client-side tooling.
 
-## Contributing
+- Ruby API: `Html2rss::Config.json_schema`
+- CLI: `html2rss schema`
+- CLI options:
+  - `html2rss schema --write tmp/html2rss-config.schema.json`
+  - `html2rss schema --no-pretty`
+- Runtime validation API: `Html2rss::Config.validate(config_hash)`
+- Runtime validation CLI: `html2rss validate config.yml`
+- Packaged JSON file: `schema/html2rss-config.schema.json`
 
-Find ideas what to contribute in:
+If you are an editor integration, automation script, or AI tool, prefer these stable discovery points:
 
-1. <https://github.com/orgs/html2rss/discussions>
-2. the issues tracker: <https://github.com/html2rss/html2rss/issues>
+- call `html2rss schema` to read the current exported schema
+- read `schema/html2rss-config.schema.json` when working from the repository or installed gem
+- use `Html2rss::Config.schema_path` if you already have Ruby loaded
+- use `Html2rss::Config.validate` or `html2rss validate config.yml` when you need authoritative runtime validation of selector references
 
-To submit changes:
+Run `bundle exec rake config:schema` before committing to regenerate `schema/html2rss-config.schema.json` and keep the checked-in JSON Schema in sync with the validators. The exported schema covers client-side validation, while runtime validation remains authoritative for dynamic cross-field checks such as selector-key references.
 
-1. Fork this repo ( <https://github.com/html2rss/html2rss/fork> )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Implement a commit your changes (`git commit -am 'feat: add XYZ'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request using the Github web UI
+## 📄 License
 
-## Development Helpers
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
-1. `bin/setup`: installs dependencies and sets up the development environment.
-2. for a modern Ruby development experience: install [`ruby-lsp`](https://github.com/Shopify/ruby-lsp) and integrate it to your IDE.
+## 💖 Sponsoring
 
-For example: [Ruby in Visual Studio Code](https://code.visualstudio.com/docs/languages/ruby).
+If you find `html2rss` useful, please consider [sponsoring the project](https://github.com/sponsors/gildesmarais).