docs(ruby-gem): align reference pages with current config surface

gildesmarais · gildesmarais · commit 6043ee61d7f4 · 2026-03-10T21:50:09.000+01:00
diff --git a/src/content/docs/ruby-gem/reference/auto-source.mdx b/src/content/docs/ruby-gem/reference/auto-source.mdx
@@ -33,9 +33,11 @@ You can customize `auto_source` to improve its accuracy.
 
 ### Scraper Options
 
-Enable or disable specific scrapers and adjust their settings:
+Enable or disable specific scrapers and adjust their settings in a complete feed config:
 
 ```yaml
+channel:
+  url: https://example.com
 auto_source:
   scraper:
     schema:
@@ -55,6 +57,8 @@ auto_source:
 Remove unwanted items from the results:
 
 ```yaml
+channel:
+  url: https://example.com
 auto_source:
   cleanup:
     keep_different_domain: false # default: true
diff --git a/src/content/docs/ruby-gem/reference/channel.mdx b/src/content/docs/ruby-gem/reference/channel.mdx
@@ -3,7 +3,9 @@ title: Channel
 description: "Learn about the channel configuration block for RSS feed metadata. Configure feed title, description, author, and other RSS channel properties."
 ---
 
-The `channel` configuration block defines the metadata for your RSS feed.
+The `channel` configuration block defines your feed metadata.
+
+This example is a complete feed config so you can see the `channel` block in context:
 
 ```yaml
 channel:
@@ -12,8 +14,16 @@ channel:
   description: "A feed of the latest news from Example.com"
   author: "jane.doe@example.com (Jane Doe)"
   ttl: 60
-  language: "en-us"
+  language: "en"
   time_zone: "Europe/Berlin"
+selectors:
+  items:
+    selector: "article"
+  title:
+    selector: "h2"
+  url:
+    selector: "a"
+    extractor: "href"
 ```
 
 ## Options
@@ -28,6 +38,12 @@ channel:
 | `language`    | Optional     | The language of the feed. Defaults to the `lang` attribute of the `<html>` tag.                                                          |
 | `time_zone`   | Optional     | The time zone for parsing dates. See the [list of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). |
 
+## Notes
+
+- `language` is runtime-validated. Use a valid language code such as `en`, not an arbitrary string.
+- `author` should follow the RSS-style `email (Name)` format when you set it explicitly.
+- `time_zone` must be a known TZ database identifier such as `UTC` or `Europe/Berlin`.
+
 ---
 
 For detailed documentation on the Ruby API, see the [official YARD documentation](https://www.rubydoc.info/gems/html2rss).
diff --git a/src/content/docs/ruby-gem/reference/cli-reference.mdx b/src/content/docs/ruby-gem/reference/cli-reference.mdx
@@ -3,50 +3,92 @@ title: CLI Reference
 description: Complete reference for the html2rss command-line interface
 ---
 
-This section provides a reference for the `html2rss` command-line interface (CLI).
+This page documents the `html2rss` command-line interface (CLI).
 
 For detailed documentation on the Ruby API, please refer to the official YARD documentation.
 
 [**📚 View the Ruby API Docs on rubydoc.info**](https://www.rubydoc.info/gems/html2rss)
 
----
+## Commands
+
+The `html2rss` executable is the primary way to interact with the gem from your terminal.
+
+### Auto
 
-### Command-Line Interface (CLI)
+Automatically discovers items from a page and prints the generated RSS feed to stdout.
+
+```bash
+# Use the default faraday strategy
+html2rss auto https://example.com/articles
 
-The `html2rss` executable provides the primary way to interact with the tool from your terminal.
+# Force browserless for JavaScript-heavy pages
+html2rss auto https://example.com/app --strategy browserless
 
-#### `html2rss auto <URL>`
+# Hint the item selector while keeping auto enhancement
+html2rss auto https://example.com/articles --items_selector ".post-card"
+```
 
-Automatically generates an RSS feed from the provided URL.
+Command: `html2rss auto URL`
 
-- `<URL>` (Required): The URL of the website to generate a feed from.
+### Feed
 
-**Example:**
+Loads a YAML config, builds the feed, and prints the RSS XML to stdout.
 
 ```bash
-html2rss auto https://unmatchedstyle.com/
+# Single-feed config
+html2rss feed single.yml
+
+# Multi-feed config under the `feeds:` key
+html2rss feed feeds.yml my-first-feed
+
+# Override the request strategy at runtime
+html2rss feed single.yml --strategy browserless
+
+# Pass dynamic parameters into %<param>s placeholders
+html2rss feed single.yml --params id:42 foo:bar
 ```
 
-#### `html2rss feed <CONFIG_FILE>`
+Command: `html2rss feed YAML_FILE [feed_name]`
 
-Generates an RSS feed based on the provided YAML configuration file.
+### Schema
 
-- `<CONFIG_FILE>` (Required): Path to your YAML configuration file.
+Prints the exported JSON Schema for the current gem version.
 
-**Examples:**
+```bash
+# Pretty-printed JSON (default)
+html2rss schema
+
+# Compact JSON
+html2rss schema --no-pretty
+
+# Write the schema to a file
+html2rss schema --write tmp/html2rss-config.schema.json
+```
+
+Command: `html2rss schema`
+
+### Validate
+
+Validates a config with the runtime validator without generating a feed.
 
 ```bash
-# Generate and print to console
-html2rss feed my_feed.yml
+# Validate a single-feed file
+html2rss validate single.yml
 
-# Generate and save to an XML file
-html2rss feed my_feed.yml > my_feed.xml
+# Validate one feed from a multi-feed file
+html2rss validate feeds.yml my-first-feed
 ```
 
-#### `html2rss help`
+Command: `html2rss validate YAML_FILE [feed_name]`
+
+### Help
 
 Displays the help message with available commands and options.
 
-#### `html2rss --version`
+Command: `html2rss help`
+
+### Version
+
+Displays the installed version of `html2rss`.
 
-Displays the currently installed version of `html2rss`.
+Command: `html2rss --version`
diff --git a/src/content/docs/ruby-gem/reference/headers.mdx b/src/content/docs/ruby-gem/reference/headers.mdx
@@ -7,13 +7,22 @@ The `headers` key allows you to set custom HTTP headers for your requests. This
 
 ## Configuration
 
-You can add any number of headers to your configuration:
+You can add any number of headers to your configuration. This example is a complete, valid feed config:
 
 ```yaml
 headers:
   User-Agent: "Mozilla/5.0 (compatible; html2rss/1.0)"
   Authorization: "Bearer YOUR_TOKEN"
   Accept: "application/json"
+channel:
+  url: "https://api.example.com/posts"
+selectors:
+  items:
+    selector: "array > object"
+  title:
+    selector: "title"
+  url:
+    selector: "url"
 ```
 
 ## Dynamic Parameters
diff --git a/src/content/docs/ruby-gem/reference/selectors.mdx b/src/content/docs/ruby-gem/reference/selectors.mdx
@@ -48,6 +48,32 @@ Available options:
 - `"reverse"`: Reverses the order of items (useful when the website shows oldest items first)
 - Default: Items appear in the order they are found on the page
 
+## Paginated Feeds
+
+`html2rss` can follow a single `rel="next"` pagination chain when you configure `selectors.items.pagination.max_pages`.
+
+```yml
+channel:
+  url: "https://example.com/news"
+selectors:
+  items:
+    selector: "article"
+    pagination:
+      max_pages: 3
+  title:
+    selector: "h1"
+  url:
+    selector: "a"
+    extractor: "href"
+```
+
+Behavior:
+
+- `max_pages` is the total page budget for the item selector chain, including the initial page.
+- Pagination follows strict `link[rel~="next"]` or `a[rel~="next"]` targets only.
+- Pagination stops when there is no next link, a page repeats, or the shared request budget is exhausted.
+- The same request safeguards apply to pagination and Browserless navigation, including timeout limits, redirect limits, response-size guards, and private-network denial.
+
 ## RSS 2.0 Selectors
 
 While you can define any named selector, only the following are used in the final RSS feed:
diff --git a/src/content/docs/ruby-gem/reference/strategy.mdx b/src/content/docs/ruby-gem/reference/strategy.mdx
@@ -27,10 +27,20 @@ docker run \
 
 ### Configuration
 
-Set the `strategy` to `browserless` in your feed configuration:
+Set the `strategy` at the top level of your feed configuration:
 
 ```yml
 strategy: browserless
+channel:
+  url: "https://example.com/app"
+selectors:
+  items:
+    selector: ".article"
+  title:
+    selector: "h2"
+  url:
+    selector: "a"
+    extractor: "href"
 ```
 
 ### Command-Line Usage
@@ -39,11 +49,12 @@ You can also specify the strategy on the command line:
 
 ```sh
 # Set environment variables for your Browserless.io instance
-BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000"
-BROWSERLESS_IO_API_TOKEN="6R0W53R135510"
+BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000" \
+BROWSERLESS_IO_API_TOKEN="6R0W53R135510" \
+  html2rss feed my_config.yml --strategy browserless
 
-# Use the browserless strategy
-html2rss feed --strategy=browserless my_config.yml
+# Or rely on the strategy stored in the YAML config
+html2rss feed my_config.yml
 ```
 
 ---
diff --git a/src/content/docs/ruby-gem/reference/stylesheets.mdx b/src/content/docs/ruby-gem/reference/stylesheets.mdx
@@ -16,7 +16,7 @@ Styling your RSS feed provides several benefits:
 
 ## Configuration
 
-You can add multiple stylesheets to your configuration:
+You can add multiple stylesheets to a normal feed configuration:
 
 ```yaml
 stylesheets:
@@ -26,6 +26,16 @@ stylesheets:
   - href: "https://example.com/rss.css"
     media: "all"
     type: "text/css"
+channel:
+  url: "https://example.com/articles"
+selectors:
+  items:
+    selector: "article"
+  title:
+    selector: "h2"
+  url:
+    selector: "a"
+    extractor: "href"
 ```
 
 ## Further Reading
