From f1b6a86930a293ca4a6416ec0292f5e4e1963146 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 2 Aug 2026 03:27:20 +0200
Subject: [PATCH 01/13] docs(ruby-gem): document pagination strategies and
 request ceilings

---
 .../docs/ruby-gem/reference/selectors.mdx     | 137 ++++++++++++++++--
 1 file changed, 121 insertions(+), 16 deletions(-)

diff --git a/src/content/docs/ruby-gem/reference/selectors.mdx b/src/content/docs/ruby-gem/reference/selectors.mdx
index d25da5df..9b4e5578 100644
--- a/src/content/docs/ruby-gem/reference/selectors.mdx
+++ b/src/content/docs/ruby-gem/reference/selectors.mdx
@@ -61,34 +61,139 @@ Available options:
 
 ## Paginated Feeds
 
-`html2rss` can follow a single `rel="next"` pagination chain when you configure `selectors.items.pagination.max_pages`.
+Configure `selectors.items.pagination` to fetch items across multiple pages. `html2rss` supports several pagination strategies to handle different website architectures.
+
+### Common Options
+
+- **`strategy`**: The pagination strategy name (default: `rel_next`).
+- **`max_pages`**: The total page budget for the item selector chain, including the initial page (default: `5`).
+
+If you specify `pagination` as a simple integer (e.g., `pagination: 5`), it defaults to the `rel_next` strategy with the specified `max_pages`.
+
+---
+
+### Strategies
+
+#### 1. `rel_next` (Default)
+
+Follows standard HTML next page relationships via `<link rel="next">` or `<a rel="next">` tags.
+
+<Code
+  code={`
+  selectors:
+    items:
+      selector: "article"
+      pagination: 5 # or { strategy: rel_next, max_pages: 5 }
+  `}
+  lang="yml"
+/>
+
+#### 2. `custom_selector`
+
+Uses a custom CSS or XPath selector to locate the link pointing to the next page. It reads the element's `href` attribute or text content as the next URL.
+
+- **`selector`** (String, required): The CSS selector or XPath expression for the next-page element.
 
 <Code
   code={`
-  channel:
-    url: "https://example.com/news"
   selectors:
     items:
       selector: "article"
       pagination:
-        max_pages: 3
-    title:
-      selector: "h1"
-    url:
-      selector: "a"
-      extractor: "href"
+        strategy: custom_selector
+        selector: "a.next-page-link"
+        max_pages: 5
+  `}
+  lang="yml"
+/>
+
+#### 3. `url_template`
+
+Increments a page number in a query parameter or replaces a `{page}` token inside the URL template.
+
+- **`param`** (String, default: `page`): The name of the query parameter representing the page number.
+- **`start_page`** (Integer, default: `1`): The initial page number.
+- **`step`** (Integer, default: `1`): The step value to increment by for each subsequent page.
+
+If the initial URL contains the `{page}` placeholder, `html2rss` replaces `{page}` with the calculated page number. Otherwise, it appends/replaces the query parameter specified by `param`.
+
+<Code
+  code={`
+  selectors:
+    items:
+      selector: "article"
+      pagination:
+        strategy: url_template
+        param: "page"
+        start_page: 1
+        step: 1
+        max_pages: 5
+  `}
+  lang="yml"
+/>
+
+#### 4. `offset`
+
+Increments a numeric offset in a query parameter or replaces an `{offset}` token inside the URL template.
+
+- **`param`** (String, default: `offset`): The name of the query parameter representing the offset.
+- **`start_offset`** (Integer, default: `0`): The initial offset value.
+- **`increment`** (Integer, default: `20`): The offset value to add for each subsequent page.
+
+If the initial URL contains the `{offset}` placeholder, `html2rss` replaces `{offset}` with the calculated offset. Otherwise, it appends/replaces the query parameter specified by `param`.
+
+<Code
+  code={`
+  selectors:
+    items:
+      selector: "article"
+      pagination:
+        strategy: offset
+        param: "offset"
+        start_offset: 0
+        increment: 20
+        max_pages: 5
   `}
   lang="yml"
 />
 
-Behavior:
+#### 5. `json_cursor`
+
+Digs next-page URLs or cursor tokens directly from JSON response payloads.
+
+Requires configuring **either** `cursor_path` or `next_url_path`:
+
+- **`cursor_path`** (String): Dot-notation path to the cursor value in the JSON payload (e.g., `meta.next_cursor`). When present, `html2rss` appends/updates the query parameter specified by `param` (defaults to `cursor`) with the cursor value.
+- **`next_url_path`** (String): Dot-notation path to the next page URL in the JSON payload (e.g., `links.next`).
+- **`param`** (String, default: `cursor`): The query parameter name used with `cursor_path`.
+
+<Code
+  code={`
+  selectors:
+    items:
+      selector: "items"
+      pagination:
+        strategy: json_cursor
+        cursor_path: "meta.next_cursor" # or next_url_path: "links.next"
+        param: "cursor"
+        max_pages: 5
+  `}
+  lang="yml"
+/>
+
+---
 
-- `max_pages` is the total page budget for the item selector chain, including the initial page.
-- `max_pages` is capped by the system request ceiling of 10 pages per feed build.
-- Pagination follows strict `link[rel~="next"]` or `a[rel~="next"]` targets only.
-- Follow-up pages use the current page's effective origin after redirects.
-- 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.
+### Behavior & Request Budgeting
+
+- **Auto-budgeting**: The request budget (`max_requests`) is automatically calculated and adjusted based on your `max_pages` configuration so you do not need to manually configure `request.max_requests` under normal circumstances.
+- **System ceiling**: The absolute request limit is capped at `10` requests per build. If `max_pages` exceeds the system request ceiling, it will be clamped to the ceiling, and a warning will be logged.
+- **Stop conditions**: Pagination stops automatically if:
+  - The configured `max_pages` is reached.
+  - The request budget is exhausted.
+  - A page yields 0 new items.
+  - An already visited URL is encountered (loop protection).
+  - A network or extraction error occurs.
+- **Request safeguards**: All request safeguards apply to pagination (such as redirect limits, timeout boundaries, private-network denial, and response-size limits).
 
 ## RSS 2.0 Selectors
 

From d18ca187e8cfa9933d46e7e54ee83cec71641966 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 2 Aug 2026 11:36:29 +0200
Subject: [PATCH 02/13] docs(ruby-gem): absorb botasaurus and schema detail
 from gem README

Move request-strategy options, payload shape, policy notes, and schema
discovery points onto the website so the gem README can stay slim.
---
 src/content/docs/ruby-gem/index.mdx           |  7 ++-
 .../docs/ruby-gem/reference/strategy.mdx      | 54 +++++++++++++------
 2 files changed, 42 insertions(+), 19 deletions(-)

diff --git a/src/content/docs/ruby-gem/index.mdx b/src/content/docs/ruby-gem/index.mdx
index 9d7a39b8..4fe10115 100644
--- a/src/content/docs/ruby-gem/index.mdx
+++ b/src/content/docs/ruby-gem/index.mdx
@@ -10,8 +10,11 @@ This section provides comprehensive documentation for the `html2rss` Ruby gem.
 If you are looking for the stable machine-readable contract for config authoring, use the JSON Schema exported by the core repo:
 
 - Repository file: [**`html2rss-config.schema.json`**](https://github.com/html2rss/html2rss/blob/master/schema/html2rss-config.schema.json)
-- CLI export: `html2rss schema`
-- Runtime validation: `html2rss validate config.yml`
+- CLI export: `html2rss schema` (also `--write`, `--no-pretty`)
+- Runtime validation: `html2rss validate config.yml` or `Html2rss::Config.validate`
+- Ruby discovery: `Html2rss::Config.json_schema` / `Html2rss::Config.schema_path`
+
+The exported schema covers client-side validation. Runtime validation remains authoritative for dynamic cross-field checks such as selector-key references. Contributors regenerating the checked-in artifact should run `bundle exec rake config:schema` in the core repo.
 
 ## Getting Started
 
diff --git a/src/content/docs/ruby-gem/reference/strategy.mdx b/src/content/docs/ruby-gem/reference/strategy.mdx
index c8219ccd..d8ff6a0c 100644
--- a/src/content/docs/ruby-gem/reference/strategy.mdx
+++ b/src/content/docs/ruby-gem/reference/strategy.mdx
@@ -22,6 +22,10 @@ The default strategy chain is:
 
 `faraday` -> `botasaurus` -> `browserless`
 
+Auto fallback shares one request budget across all strategy attempts. For pagination-heavy or dynamic pages, increase `request.max_requests` (or `--max-requests`) when retries exhaust the budget.
+
+Auto fallback decisions are hidden at the default `LOG_LEVEL=warn`; run with `LOG_LEVEL=info` to include them in CLI output.
+
 ## `browserless`
 
 To use the `browserless` strategy, you need a running instance of [Browserless.io](https://www.browserless.io/).
@@ -169,39 +173,55 @@ For custom Browserless websocket endpoints, `BROWSERLESS_IO_API_TOKEN` is mandat
 - `strategy: botasaurus`
 - `BOTASAURUS_SCRAPER_URL` set to your Botasaurus scrape API base URL (for example `http://localhost:4010`)
 
+html2rss still enforces local request policy preflight and timeout budget. Botasaurus handles browser navigation/rendering internals, so some policy details are delegated to upstream execution.
+
 ### Configuration
 
 <Code
   code={`
+  channel:
+    url: "https://example.com"
   strategy: botasaurus
+  auto_source: {}
   request:
-    max_redirects: 5
-    max_requests: 6
     botasaurus:
       navigation_mode: auto
       max_retries: 2
       headless: false
-  channel:
-    url: "https://example.com/protected-listing"
-  auto_source: {}
   `}
   lang="yml"
 />
 
 Supported `request.botasaurus` options:
 
-- `navigation_mode` (`auto`, `get`, `google_get`, `google_get_bypass`)
-- `max_retries` (`0..3`)
-- `wait_for_selector`
-- `wait_timeout_seconds`
-- `block_images`
-- `block_images_and_css`
-- `wait_for_complete_page_load`
-- `headless`
-- `proxy`
-- `user_agent`
-- `window_size` (two integers, for example `[1920, 1080]`)
-- `lang`
+- `navigation_mode` (`auto`, `get`, `google_get`, `google_get_bypass`; default `auto`)
+- `max_retries` (`0..3`; default `2`)
+- `wait_for_selector` (string)
+- `wait_timeout_seconds` (integer)
+- `block_images` (boolean)
+- `block_images_and_css` (boolean)
+- `wait_for_complete_page_load` (boolean)
+- `headless` (boolean, default `false`)
+- `proxy` (string)
+- `user_agent` (string)
+- `window_size` (two-item integer array, for example `[1920, 1080]`)
+- `lang` (string, for example `en-US`)
+
+### Request payload shape
+
+Example scrape-API payload shape:
+
+<Code
+  code={`
+  {
+    "url": "https://example.com",
+    "navigation_mode": "auto",
+    "max_retries": 2,
+    "headless": false
+  }
+  `}
+  lang="json"
+/>
 
 ### Command-Line Usage
 

From 236f1faba4154407d3dcfaf3ced29e12b9a20f60 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 10 Aug 2026 13:56:38 +0200
Subject: [PATCH 03/13] docs(auto_source): add sitemap scraper reference and
 configuration options

---
 .../docs/ruby-gem/reference/auto-source.mdx        | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/src/content/docs/ruby-gem/reference/auto-source.mdx b/src/content/docs/ruby-gem/reference/auto-source.mdx
index 277db98e..110b84c8 100644
--- a/src/content/docs/ruby-gem/reference/auto-source.mdx
+++ b/src/content/docs/ruby-gem/reference/auto-source.mdx
@@ -23,10 +23,12 @@ To enable it, add `auto_source: {}` to your configuration:
 `auto_source` uses the following strategies to find content:
 
 1.  **`wordpress_api`:** Detects the `<link rel="https://api.w.org/">` tag used by WordPress and pulls posts from the REST API without parsing article HTML. See [WordPress API](/ruby-gem/reference/wordpress-api/).
-2.  **`schema`:** Parses `<script type="json/ld">` tags containing structured data (e.g., [Schema.org](https://schema.org/)).
-3.  **`semantic_html`:** Searches for semantic HTML5 tags like `<article>`, `<main>`, and `<section>`.
-4.  **`html`:** Analyzes the HTML structure to find frequently occurring selectors that are likely to contain the main content.
-5.  **json_state:** Single-page applications often stash pre-rendered article data in `<script type="application/json">` tags or global variables
+2.  **`sitemap`:** Automatically locates XML sitemap documents (`<link rel="sitemap">`, `/sitemap.xml`, or `/robots.txt`), filtering entries by priority and recency, with support for Google News tags (`<news:news>`).
+3.  **`schema`:** Parses `<script type="json/ld">` tags containing structured data (e.g., [Schema.org](https://schema.org/)).
+4.  **`microdata`:** Extracts HTML Microdata annotations (`itemscope itemtype`).
+5.  **`semantic_html`:** Searches for semantic HTML5 tags like `<article>`, `<main>`, and `<section>`.
+6.  **`html`:** Analyzes the HTML structure to find frequently occurring selectors that are likely to contain the main content.
+7.  **`json_state`:** Single-page applications often stash pre-rendered article data in `<script type="application/json">` tags or global variables
     such as `window.__NEXT_DATA__`, `window.__NUXT__`, or `window.STATE`. The JSON-state scraper walks those blobs, finds arrays with
     `title`/`url` pairs, and converts them into the same hashes produced by `HtmlExtractor`.
 
@@ -51,6 +53,10 @@ Enable or disable specific scrapers and adjust their settings:
     scraper:
       wordpress_api:
         enabled: false # default: true
+      sitemap:
+        enabled: true # default: true
+        min_priority: 0.3 # default: 0.3
+        max_age_days: 30 # default: 30
       schema:
         enabled: false # default: true
       semantic_html:

From 963b0129c19b9dbc0fe69d21dec2bcc96ff5cd83 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 10 Aug 2026 17:16:28 +0200
Subject: [PATCH 04/13] docs(auto_source): add meta_oembed scraper reference
 and configuration options

---
 src/content/docs/ruby-gem/reference/auto-source.mdx | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/src/content/docs/ruby-gem/reference/auto-source.mdx b/src/content/docs/ruby-gem/reference/auto-source.mdx
index 110b84c8..65edebc9 100644
--- a/src/content/docs/ruby-gem/reference/auto-source.mdx
+++ b/src/content/docs/ruby-gem/reference/auto-source.mdx
@@ -24,11 +24,12 @@ To enable it, add `auto_source: {}` to your configuration:
 
 1.  **`wordpress_api`:** Detects the `<link rel="https://api.w.org/">` tag used by WordPress and pulls posts from the REST API without parsing article HTML. See [WordPress API](/ruby-gem/reference/wordpress-api/).
 2.  **`sitemap`:** Automatically locates XML sitemap documents (`<link rel="sitemap">`, `/sitemap.xml`, or `/robots.txt`), filtering entries by priority and recency, with support for Google News tags (`<news:news>`).
-3.  **`schema`:** Parses `<script type="json/ld">` tags containing structured data (e.g., [Schema.org](https://schema.org/)).
-4.  **`microdata`:** Extracts HTML Microdata annotations (`itemscope itemtype`).
-5.  **`semantic_html`:** Searches for semantic HTML5 tags like `<article>`, `<main>`, and `<section>`.
-6.  **`html`:** Analyzes the HTML structure to find frequently occurring selectors that are likely to contain the main content.
-7.  **`json_state`:** Single-page applications often stash pre-rendered article data in `<script type="application/json">` tags or global variables
+3.  **`meta_oembed`:** Extracts single-item articles, video pages, and media updates from OpenGraph/Twitter meta tags and resolves JSON oEmbed endpoints (`<link rel="alternate" type="application/json+oembed">`).
+4.  **`schema`:** Parses `<script type="json/ld">` tags containing structured data (e.g., [Schema.org](https://schema.org/)).
+5.  **`microdata`:** Extracts HTML Microdata annotations (`itemscope itemtype`).
+6.  **`semantic_html`:** Searches for semantic HTML5 tags like `<article>`, `<main>`, and `<section>`.
+7.  **`html`:** Analyzes the HTML structure to find frequently occurring selectors that are likely to contain the main content.
+8.  **`json_state`:** Single-page applications often stash pre-rendered article data in `<script type="application/json">` tags or global variables
     such as `window.__NEXT_DATA__`, `window.__NUXT__`, or `window.STATE`. The JSON-state scraper walks those blobs, finds arrays with
     `title`/`url` pairs, and converts them into the same hashes produced by `HtmlExtractor`.
 
@@ -57,6 +58,8 @@ Enable or disable specific scrapers and adjust their settings:
         enabled: true # default: true
         min_priority: 0.3 # default: 0.3
         max_age_days: 30 # default: 30
+      meta_oembed:
+        enabled: true # default: true
       schema:
         enabled: false # default: true
       semantic_html:

From 33bc62b62e7ba2953db9133110aac1008a00cc57 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 10 Aug 2026 21:43:20 +0200
Subject: [PATCH 05/13] docs(cli): document --input flag, jsonfeed format, and
 schema options in CLI reference

---
 .../docs/ruby-gem/reference/cli-reference.mdx | 59 ++++++++++++++-----
 1 file changed, 44 insertions(+), 15 deletions(-)

diff --git a/src/content/docs/ruby-gem/reference/cli-reference.mdx b/src/content/docs/ruby-gem/reference/cli-reference.mdx
index 01c77e50..961c1845 100644
--- a/src/content/docs/ruby-gem/reference/cli-reference.mdx
+++ b/src/content/docs/ruby-gem/reference/cli-reference.mdx
@@ -17,21 +17,31 @@ The `html2rss` executable is the primary way to interact with the gem from your
 
 ### Auto
 
-Automatically discovers items from a page and prints the generated RSS feed to stdout.
+Automatically discovers items from a page and prints the generated RSS or JSONFeed to stdout.
 
 <Code
   code={`
   html2rss auto https://example.com/articles ; \
+  html2rss auto https://example.com/articles --format jsonfeed ; \
   html2rss auto https://example.com/app --strategy browserless --max-redirects 5 --max-requests 6 ; \
   BOTASAURUS_SCRAPER_URL="http://localhost:4010" html2rss auto https://example.com/protected --strategy botasaurus ; \
-  html2rss auto https://example.com/articles --items_selector ".post-card"
+  html2rss auto https://example.com/articles --items_selector ".post-card" ; \
+  html2rss auto --input sample.html ; \
+  html2rss auto https://example.com/articles --input sample.html
 `}
   lang="bash"
 />
 
-Command: `html2rss auto URL`
+Command: `html2rss auto [URL]`
 
-Default behavior is `--strategy auto`, which tries `faraday` then `botasaurus` then `browserless`.
+Available options:
+
+- `--strategy`: Optional request strategy (`auto`, `faraday`, `browserless`, `botasaurus`, `local_file`). Defaults to `auto`, which tries `faraday` -> `botasaurus` -> `browserless`.
+- `--format`: Output format for the auto-sourced feed (`rss` or `jsonfeed`). Defaults to `rss`.
+- `--items_selector`: Optional CSS selector hint for item extraction.
+- `--max-redirects`: Maximum redirects to follow per request.
+- `--max-requests`: Maximum requests to allow for this feed build (defaults to `4` for auto discovery).
+- `--input`: Local HTML file path to read input from without making network requests. When provided without a `URL`, `html2rss` attempts to detect the base URL from `<link rel="canonical">` or OpenGraph metadata in the HTML.
 
 #### URL Surface Guidance For `auto`
 
@@ -78,17 +88,17 @@ Start by changing the input URL to a direct listing/update page, then move to ex
 <Code
   code={`
   # 1) Start Browserless in the background
-  docker run -d --rm --name html2rss-browserless \
-    -p 3000:3000 \
-    -e "CONCURRENT=10" \
-    -e "TOKEN=6R0W53R135510" \
+  docker run -d --rm --name html2rss-browserless \\
+    -p 3000:3000 \\
+    -e "CONCURRENT=10" \\
+    -e "TOKEN=6R0W53R135510" \\
     ghcr.io/browserless/chromium
 
 # 2) Run html2rss against Browserless
 
-BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000" \
- BROWSERLESS_IO_API_TOKEN="6R0W53R135510" \
- html2rss auto https://example.com/updates --strategy browserless
+BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000" \\
+BROWSERLESS_IO_API_TOKEN="6R0W53R135510" \\
+html2rss auto https://example.com/updates --strategy browserless
 
 # 3) Stop Browserless when done
 
@@ -111,7 +121,7 @@ For custom Browserless endpoints, `BROWSERLESS_IO_API_TOKEN` is required.
 
 <Code
   code={`
-  BOTASAURUS_SCRAPER_URL="http://localhost:4010" \
+  BOTASAURUS_SCRAPER_URL="http://localhost:4010" \\
   html2rss auto https://example.com/updates --strategy botasaurus
 `}
   lang="bash"
@@ -135,18 +145,27 @@ Loads a YAML config, builds the feed, and prints the RSS XML to stdout.
   html2rss feed single.yml --strategy browserless ; \
   BOTASAURUS_SCRAPER_URL="http://localhost:4010" html2rss feed single.yml --strategy botasaurus ; \
   html2rss feed single.yml --max-redirects 5 --max-requests 6 ; \
-  html2rss feed single.yml --params id:42 foo:bar
+  html2rss feed single.yml --params id:42 foo:bar ; \
+  html2rss feed single.yml --input sample.html
 `}
   lang="bash"
 />
 
 Command: `html2rss feed YAML_FILE [feed_name]`
 
+Available options:
+
+- `--strategy`: Request strategy override (`auto`, `faraday`, `browserless`, `botasaurus`, `local_file`).
+- `--params`: Dynamic parameters passed as key-value pairs (e.g. `--params id:42 section:news`).
+- `--max-redirects`: Maximum redirects to follow per request.
+- `--max-requests`: Total request budget allowed for this feed build.
+- `--input`: Local HTML file path to read input from instead of making a network request.
+
 The CLI keeps `strategy` as a top-level override and writes runtime request limits into the generated config under `request`.
 
 ### Schema
 
-Prints the exported JSON Schema for the current gem version.
+Prints or writes the exported JSON Schema for the current gem version.
 
 <Code
   code={`
@@ -159,6 +178,11 @@ Prints the exported JSON Schema for the current gem version.
 
 Command: `html2rss schema`
 
+Available options:
+
+- `--pretty` / `--no-pretty`: Pretty-print the schema JSON (default: `true`).
+- `--write PATH`: Write the schema JSON directly to the given file path, creating any missing parent directories.
+
 ### Validate
 
 Validates a config with the runtime validator without generating a feed.
@@ -166,13 +190,18 @@ Validates a config with the runtime validator without generating a feed.
 <Code
   code={`
   html2rss validate single.yml ; \
-  html2rss validate feeds.yml my-first-feed
+  html2rss validate feeds.yml my-first-feed ; \
+  html2rss validate single.yml --params id:42
 `}
   lang="bash"
 />
 
 Command: `html2rss validate YAML_FILE [feed_name]`
 
+Available options:
+
+- `--params`: Dynamic parameters to interpolate before validation (default: `{}`).
+
 ### Help
 
 Displays the help message with available commands and options.

From 91d4abe525a126d36756bd0de1e091633afde71f Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 10 Aug 2026 21:43:35 +0200
Subject: [PATCH 06/13] docs(strategy): document local_file strategy,
 total_timeout_seconds, and default user agent

---
 .../docs/ruby-gem/reference/strategy.mdx      | 54 +++++++++++++++----
 1 file changed, 45 insertions(+), 9 deletions(-)

diff --git a/src/content/docs/ruby-gem/reference/strategy.mdx b/src/content/docs/ruby-gem/reference/strategy.mdx
index d8ff6a0c..b94f6545 100644
--- a/src/content/docs/ruby-gem/reference/strategy.mdx
+++ b/src/content/docs/ruby-gem/reference/strategy.mdx
@@ -11,6 +11,7 @@ The `strategy` key defines how `html2rss` fetches a website's content.
 - **`faraday`**: Makes a direct HTTP request. It is fast but does not execute JavaScript.
 - **`browserless`**: Renders the website in a headless Chrome browser, which is necessary for JavaScript-heavy sites.
 - **`botasaurus`**: Delegates fetching to a Botasaurus scrape API. This is opt-in and requires `BOTASAURUS_SCRAPER_URL`.
+- **`local_file`**: Reads HTML content directly from a local file on disk without making network requests.
 
 `strategy` is a top-level config key. Request-specific controls live under `request`.
 
@@ -26,6 +27,37 @@ Auto fallback shares one request budget across all strategy attempts. For pagina
 
 Auto fallback decisions are hidden at the default `LOG_LEVEL=warn`; run with `LOG_LEVEL=info` to include them in CLI output.
 
+## `faraday`
+
+`faraday` is the standard static HTTP transport. When no custom `User-Agent` header is supplied in `headers`, `html2rss` sends `html2rss/<VERSION>` by default.
+
+## `local_file`
+
+`local_file` parses content directly from a local file on disk. It is designed for offline testing, local fixtures, and CLI `--input` workflows.
+
+Because no remote network connection is established, `local_file` skips remote network guards and SSRF preflight checks.
+
+### Configuration
+
+<Code
+  code={`
+  strategy: local_file
+  request:
+    local_file_path: "tmp/page.html"
+  channel:
+    url: "https://example.com/articles"
+  selectors:
+    items:
+      selector: ".article"
+    title:
+      selector: "h2"
+    url:
+      selector: "a"
+      extractor: "href"
+  `}
+  lang="yml"
+/>
+
 ## `browserless`
 
 To use the `browserless` strategy, you need a running instance of [Browserless.io](https://www.browserless.io/).
@@ -36,11 +68,11 @@ You can run a local Browserless.io instance using Docker:
 
 <Code
   code={`
-  docker run \
-    --rm \
-    -p 3000:3000 \
-    -e "CONCURRENT=10" \
-    -e "TOKEN=6R0W53R135510" \
+  docker run \\
+    --rm \\
+    -p 3000:3000 \\
+    -e "CONCURRENT=10" \\
+    -e "TOKEN=6R0W53R135510" \\
     ghcr.io/browserless/chromium
 `}
   lang="sh"
@@ -56,6 +88,7 @@ Set the `strategy` at the top level of your feed configuration and put request c
   request:
     max_redirects: 5
     max_requests: 6
+    total_timeout_seconds: 30
   channel:
     url: "https://example.com/app"
   selectors:
@@ -74,10 +107,12 @@ Set the `strategy` at the top level of your feed configuration and put request c
 
 Use this split consistently:
 
-- `strategy`: selects `auto`, `faraday`, `browserless`, or `botasaurus`
-- `headers`: top-level headers shared by all strategies
-- `request.max_redirects`: redirect limit for the request session
-- `request.max_requests`: total request budget for the whole feed build
+- `strategy`: selects `auto`, `faraday`, `browserless`, `botasaurus`, or `local_file`
+- `headers`: top-level headers shared by remote strategies (defaults to `html2rss/<VERSION>` User-Agent)
+- `request.max_redirects`: redirect limit for the request session (default: `5`)
+- `request.max_requests`: total request budget for the whole feed build (default: `10`)
+- `request.total_timeout_seconds`: maximum total wall-clock budget for the entire feed build
+- `request.local_file_path`: file path for `local_file` strategy
 - `request.browserless.*`: Browserless-only options
 - `request.botasaurus.*`: Botasaurus-only options
 
@@ -91,6 +126,7 @@ Example:
   request:
     max_redirects: 5
     max_requests: 6
+    total_timeout_seconds: 45
     browserless:
       preload:
         wait_after_ms: 5000

From a6b61ab6d360ab27d927b213c76194fe1a39cef5 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 10 Aug 2026 21:43:47 +0200
Subject: [PATCH 07/13] docs(configuration): use Code component for Ruby
 snippet in global configuration

---
 .../docs/ruby-gem/reference/configuration.mdx   | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/src/content/docs/ruby-gem/reference/configuration.mdx b/src/content/docs/ruby-gem/reference/configuration.mdx
index fc43dceb..9dad7c29 100644
--- a/src/content/docs/ruby-gem/reference/configuration.mdx
+++ b/src/content/docs/ruby-gem/reference/configuration.mdx
@@ -9,16 +9,19 @@ You can configure global defaults for `html2rss` using `Html2rss.configure`. Thi
 
 Global configuration is thread-safe and implements an RCU (Read-Copy-Update) mechanism: once configured, the global configuration instance is frozen and thread-safe.
 
-```ruby
-require 'html2rss'
+<Code
+  code={`
+  require 'html2rss'
 
 Html2rss.configure do |config|
-  config.log_level = :info
-  config.min_ttl = 60
-  config.default_strategy = :faraday
-  config.headers = { 'User-Agent' => 'MyCustomUserAgent/1.0' }
+config.log_level = :info
+config.min_ttl = 60
+config.default_strategy = :faraday
+config.headers = { 'User-Agent' => 'MyCustomUserAgent/1.0' }
 end
-```
+`}
+lang="ruby"
+/>
 
 ## Options
 

From aba6dfb9c216d78a17355b909b086486134840df Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 10 Aug 2026 21:43:58 +0200
Subject: [PATCH 08/13] docs(auto_source): document microformats2 scraper,
 fallback_anchorless options, and teaser extraction

---
 .../docs/ruby-gem/reference/auto-source.mdx   | 21 +++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/src/content/docs/ruby-gem/reference/auto-source.mdx b/src/content/docs/ruby-gem/reference/auto-source.mdx
index 65edebc9..459ab67d 100644
--- a/src/content/docs/ruby-gem/reference/auto-source.mdx
+++ b/src/content/docs/ruby-gem/reference/auto-source.mdx
@@ -25,13 +25,16 @@ To enable it, add `auto_source: {}` to your configuration:
 1.  **`wordpress_api`:** Detects the `<link rel="https://api.w.org/">` tag used by WordPress and pulls posts from the REST API without parsing article HTML. See [WordPress API](/ruby-gem/reference/wordpress-api/).
 2.  **`sitemap`:** Automatically locates XML sitemap documents (`<link rel="sitemap">`, `/sitemap.xml`, or `/robots.txt`), filtering entries by priority and recency, with support for Google News tags (`<news:news>`).
 3.  **`meta_oembed`:** Extracts single-item articles, video pages, and media updates from OpenGraph/Twitter meta tags and resolves JSON oEmbed endpoints (`<link rel="alternate" type="application/json+oembed">`).
-4.  **`schema`:** Parses `<script type="json/ld">` tags containing structured data (e.g., [Schema.org](https://schema.org/)).
+4.  **`schema`:** Parses `<script type="json/ld">` tags containing structured data (e.g., [Schema.org](https://schema.org/)), extracting authors and publishers.
 5.  **`microdata`:** Extracts HTML Microdata annotations (`itemscope itemtype`).
-6.  **`semantic_html`:** Searches for semantic HTML5 tags like `<article>`, `<main>`, and `<section>`.
-7.  **`html`:** Analyzes the HTML structure to find frequently occurring selectors that are likely to contain the main content.
-8.  **`json_state`:** Single-page applications often stash pre-rendered article data in `<script type="application/json">` tags or global variables
+6.  **`microformats2`:** Parses Microformats2 `h-entry` markup, extracting `p-name`, `e-content`, `u-url`, `dt-published`, `p-author`, `p-category`, and `u-photo` / `u-featured` media.
+7.  **`semantic_html`:** Searches for semantic HTML5 tags like `<article>`, `<main>`, and `<section>`, with fallback clustering for anchorless lists.
+8.  **`html`:** Analyzes HTML structure to find frequently occurring item selectors, with tag-structure and class-clustering fallbacks.
+9.  **`json_state`:** Single-page applications often stash pre-rendered article data in `<script type="application/json">` tags or global variables
     such as `window.__NEXT_DATA__`, `window.__NUXT__`, or `window.STATE`. The JSON-state scraper walks those blobs, finds arrays with
-    `title`/`url` pairs, and converts them into the same hashes produced by `HtmlExtractor`.
+    `title`/`url` pairs, and converts them into feed items.
+
+`auto_source` also automatically extracts and prepends kicker/teaser labels to article titles when present.
 
 **`json_state` Limitations:** the scraper requires discoverable arrays of hashes containing clear `title` and `url` fields. Minified or
 obfuscated state objects, heavily encoded values, or blobs that require executing embedded functions are ignored.
@@ -62,14 +65,20 @@ Enable or disable specific scrapers and adjust their settings:
         enabled: true # default: true
       schema:
         enabled: false # default: true
+      microdata:
+        enabled: true # default: true
+      microformats2:
+        enabled: true # default: true
       semantic_html:
-        enabled: false # default: true
+        enabled: true # default: true
+        fallback_anchorless: true # default: true
       json_state:
         enabled: false # default: true
       html:
         enabled: true
         minimum_selector_frequency: 3 # default: 2
         use_top_selectors: 3 # default: 5
+        fallback_anchorless: true # default: true
   `}
   lang="yaml"
 />

From fb2ad0c4bbb9f41f09e5ea807f0e457127a1a578 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 10 Aug 2026 21:44:21 +0200
Subject: [PATCH 09/13] docs(ruby-gem): update migration notes for purged
 legacy selector aliases and channel keys

---
 src/content/docs/creating-custom-feeds.mdx    | 44 +++++++-----
 .../guides/backward-compatibility.mdx         | 71 +++++++++++--------
 2 files changed, 68 insertions(+), 47 deletions(-)

diff --git a/src/content/docs/creating-custom-feeds.mdx b/src/content/docs/creating-custom-feeds.mdx
index 16382e65..ae828675 100644
--- a/src/content/docs/creating-custom-feeds.mdx
+++ b/src/content/docs/creating-custom-feeds.mdx
@@ -80,9 +80,9 @@ This is where you tell the html2rss engine exactly what to find on the page. You
       selector: "article.post"
     title:
       selector: "h2 a"
-    link:
+    url:
       selector: "h2 a"
-      attribute: href
+      extractor: "href"
   `}
   lang="yaml"
 />
@@ -100,21 +100,21 @@ This says: "Find each article, get the title from the h2 anchor, and get the lin
 **Step 2:** Create a file called `example.com.yml` with this basic structure:
 
 <Code
-  code={
-    "channel:\n" +
-    "  url: https://example.com/blog\n" +
-    "  title: My Blog\n" +
-    "\n" +
-    "selectors:\n" +
-    "  items:\n" +
-    '    selector: "article.post"\n' +
-    "  title:\n" +
-    '    selector: "h2 a"\n' +
-    "  link:\n" +
-    '    selector: "h2 a"\n' +
-    "    attribute: href"
-  }
-  lang="yaml"
+  code={`
+  channel:
+    url: https://example.com/blog
+    title: My Blog
+
+selectors:
+items:
+selector: "article.post"
+title:
+selector: "h2 a"
+url:
+selector: "h2 a"
+extractor: "href"
+`}
+lang="yaml"
 />
 
 **Step 3:** Test it with your html2rss-web instance or the [Ruby gem](/ruby-gem/installation/).
@@ -148,9 +148,13 @@ html2rss supports many configuration options:
 
 <Code code={`html2rss feed your-config.yml`} lang="bash" />
 
-3. **Test with `html2rss-web`:** Add your config to the `feeds.yml` file and restart your instance
+3. **Or test against a locally saved HTML file without network requests:**
+
+<Code code={`html2rss feed your-config.yml --input sample.html`} lang="bash" />
+
+4. **Test with `html2rss-web`:** Add your config to the `feeds.yml` file and restart your instance
 
-4. **Check the output:** Make sure all items have titles, links, and descriptions
+5. **Check the output:** Make sure all items have titles, links, and descriptions
 
 ### Useful CLI flags when a site is difficult
 
@@ -158,11 +162,13 @@ Some sites need a little more request budget than the defaults.
 
 - Use `--max-redirects` when the site bounces through several canonicalization or tracking redirects before the real page loads.
 - Use `--max-requests` when your config needs more than one request, for example pagination or other follow-up fetches.
+- Use `--input` to supply a local HTML file to inspect extraction offline.
 
 <Code
   code={`
   html2rss feed your-config.yml --max-redirects 10 && \
   html2rss feed your-config.yml --max-requests 5 && \
+  html2rss feed your-config.yml --input /path/to/page.html && \
   html2rss auto https://example.com/blog --max-redirects 10 --max-requests 5
 `}
   lang="bash"
diff --git a/src/content/docs/ruby-gem/guides/backward-compatibility.mdx b/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
index 92a7a6df..3aaad17a 100644
--- a/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
+++ b/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
@@ -1,54 +1,69 @@
 ---
-title: "Backward Compatibility"
-description: "html2rss maintains backward compatibility with older configuration formats and attribute names."
+title: "Backward Compatibility & Migrations"
+description: "Migration guide and backward-compatibility reference for html2rss configuration formats."
 ---
 
 import { Code } from "@astrojs/starlight/components";
 
-html2rss maintains backward compatibility with older configuration formats and attribute names.
+This page outlines recent breaking changes, purged legacy aliases, and migration steps for older feed configurations.
 
-## Renamed Attributes
+## Removed Legacy Selector Aliases
 
-Some attribute names have been renamed for clarity, but the old names still work:
+In previous versions, `html2rss` accepted legacy selector names with a deprecation warning. These shims have been removed:
 
-| Current Name   | Legacy Names         | Description                  |
-| -------------- | -------------------- | ---------------------------- |
-| `published_at` | `updated`, `pubDate` | Publication date of the item |
+| Removed Name | Required Name  | Description           |
+| :----------- | :------------- | :-------------------- |
+| `pubDate`    | `published_at` | Item publication date |
+| `updated`    | `published_at` | Item publication date |
 
-### Example
+### Migration Example
 
-Both of these configurations work identically:
+Update any occurrences of `pubDate` or `updated` in your `selectors` block to `published_at`:
 
 <Code
   code={`
-  # Current format (recommended)
+  # Deprecated / Removed
   selectors:
-    published_at:
+    updated:
       selector: ".date"
 
-# Legacy format (still supported)
+# Current & Required
 
 selectors:
-updated:
+published_at:
 selector: ".date"
-`} lang="yaml"
+`}
+lang="yaml"
 />
 
-## Migration Guide
+## Removed Channel Attributes
 
-If you're upgrading from an older version of html2rss:
+`strategy` and `headers` were previously tolerated inside the `channel` block. These legacy shims have been removed. Both keys must now be placed at the top level of your feed configuration:
 
-1. **Update attribute names**: Replace `updated` with `published_at` in your configurations
-2. **Test your feeds**: Verify that all feeds still work correctly after the update
-
-## Deprecated Features
-
-The following features are deprecated but still supported:
-
-- **Legacy attribute names**: While still supported, use the current names for new configurations
+<Code
+  code={`
+  # Deprecated / Removed
+  channel:
+    url: "https://example.com/articles"
+    strategy: browserless
+    headers:
+      User-Agent: "CustomAgent/1.0"
+
+# Current & Required
+
+strategy: browserless
+headers:
+User-Agent: "CustomAgent/1.0"
+channel:
+url: "https://example.com/articles"
+`}
+lang="yaml"
+/>
 
-## Getting Help
+## Migration Checklist
 
-If you encounter issues with backward compatibility:
+When upgrading to modern `html2rss` releases:
 
-- **Report issues**: Open an issue if you find compatibility problems
+1. **Rename date selectors**: Ensure date selectors use `published_at` rather than `updated` or `pubDate`.
+2. **Move channel-level transport keys**: Ensure `strategy` and `headers` are defined at the top level of the YAML file.
+3. **Validate configurations**: Run `html2rss validate config.yml` to ensure your YAML conforms to the current schema.

From d2951783eb80ee6625e649d603d0fe8d1e77e0b2 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 10 Aug 2026 21:53:15 +0200
Subject: [PATCH 10/13] docs: align navigation links, canonical selector keys,
 and code snippet formatting

---
 src/content/docs/index.mdx                    |  2 +-
 .../guides/advanced-content-extraction.mdx    |  4 ++--
 .../ruby-gem/guides/advanced-features.mdx     |  2 +-
 .../docs/ruby-gem/reference/selectors.mdx     | 14 ++++++------
 .../docs/ruby-gem/reference/strategy.mdx      | 22 ++++++++++---------
 .../guides/setup-for-development.mdx          | 17 +++++++-------
 src/content/docs/web-application/index.mdx    |  2 +-
 7 files changed, 32 insertions(+), 31 deletions(-)

diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
index 695e2f98..0ec4945c 100644
--- a/src/content/docs/index.mdx
+++ b/src/content/docs/index.mdx
@@ -19,7 +19,7 @@ The canonical path to your first feed:
 
 ### Features & Operations
 
-- **[Use included configs](/web-application/guides/use-included-configs/)**: Use the Feed Directory for popular sites.
+- **[Use the Feed Directory](/web-application/guides/use-the-feed-directory/)**: Use the Feed Directory for popular sites.
 - **[Monitoring](/web-application/reference/monitoring/)**: Keep your instance healthy with probes and Sentry.
 - **[Reference](/web-application/reference/)**: Environment variables and versioning strategy.
 
diff --git a/src/content/docs/ruby-gem/guides/advanced-content-extraction.mdx b/src/content/docs/ruby-gem/guides/advanced-content-extraction.mdx
index 31f7552c..b458d0ee 100644
--- a/src/content/docs/ruby-gem/guides/advanced-content-extraction.mdx
+++ b/src/content/docs/ruby-gem/guides/advanced-content-extraction.mdx
@@ -7,8 +7,8 @@ While basic selectors are straightforward, you can achieve very precise content
 
 ## Extractors
 
-Learn how to extract specific attributes (like `src` for images) or static values. See [Extractors](/ruby-gem/reference/selectors/#extractors/).
+Learn how to extract specific attributes (like `src` for images) or static values. See [Extractors](/ruby-gem/reference/selectors/#extractors).
 
 ## Post Processors
 
-Manipulate extracted text, sanitize HTML, convert Markdown, or apply custom logic. See [Post Processors](/ruby-gem/reference/selectors/#post-processors/).
+Manipulate extracted text, sanitize HTML, convert Markdown, or apply custom logic. See [Post Processors](/ruby-gem/reference/selectors/#post-processors).
diff --git a/src/content/docs/ruby-gem/guides/advanced-features.mdx b/src/content/docs/ruby-gem/guides/advanced-features.mdx
index f89cc46c..77453a4f 100644
--- a/src/content/docs/ruby-gem/guides/advanced-features.mdx
+++ b/src/content/docs/ruby-gem/guides/advanced-features.mdx
@@ -124,7 +124,7 @@ You can add custom validation by using post-processors:
       selector: "article"
     title:
       selector: "h2"
-      post_process:
+      post_processors:
         - name: "gsub"
           pattern: "^\\s*$"
           replacement: "Untitled"
diff --git a/src/content/docs/ruby-gem/reference/selectors.mdx b/src/content/docs/ruby-gem/reference/selectors.mdx
index 9b4e5578..6533ec6e 100644
--- a/src/content/docs/ruby-gem/reference/selectors.mdx
+++ b/src/content/docs/ruby-gem/reference/selectors.mdx
@@ -215,13 +215,13 @@ While you can define any named selector, only the following are used in the fina
 
 Each selector can be configured with the following options:
 
-| Name           | Description                                              |
-| -------------- | -------------------------------------------------------- |
-| `selector`     | The CSS selector for the target element.                 |
-| `extractor`    | The extractor to use for this selector.                  |
-| `attribute`    | The attribute name (required for `attribute` extractor). |
-| `static`       | The static value (required for `static` extractor).      |
-| `post_process` | A list of post-processors to apply to the value.         |
+| Name              | Description                                              |
+| ----------------- | -------------------------------------------------------- |
+| `selector`        | The CSS selector for the target element.                 |
+| `extractor`       | The extractor to use for this selector.                  |
+| `attribute`       | The attribute name (required for `attribute` extractor). |
+| `static`          | The static value (required for `static` extractor).      |
+| `post_processors` | A list of post-processors to apply to the value.         |
 
 ### Extractors
 
diff --git a/src/content/docs/ruby-gem/reference/strategy.mdx b/src/content/docs/ruby-gem/reference/strategy.mdx
index b94f6545..921baaa5 100644
--- a/src/content/docs/ruby-gem/reference/strategy.mdx
+++ b/src/content/docs/ruby-gem/reference/strategy.mdx
@@ -181,13 +181,13 @@ You can also specify the strategy on the command line:
 <Code
   code={`
   # Set environment variables for your Browserless.io instance
-  BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000" \
-  BROWSERLESS_IO_API_TOKEN="6R0W53R135510" \
-  html2rss feed my_config.yml --strategy browserless ; \
-  html2rss feed my_config.yml --max-redirects 5 --max-requests 6 ; \
-  html2rss feed my_config.yml
+  BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000" \\
+  BROWSERLESS_IO_API_TOKEN="6R0W53R135510" \\
+  html2rss feed my_config.yml --strategy browserless
+
+html2rss feed my_config.yml --max-redirects 5 --max-requests 6
 `}
-  lang="sh"
+lang="bash"
 />
 
 ### Browserless Troubleshooting
@@ -263,11 +263,13 @@ Example scrape-API payload shape:
 
 <Code
   code={`
-  BOTASAURUS_SCRAPER_URL="http://localhost:4010" \
-  html2rss auto https://example.com/updates --strategy botasaurus ; \
-  html2rss feed my_config.yml --strategy botasaurus
+  BOTASAURUS_SCRAPER_URL="http://localhost:4010" \\
+  html2rss auto https://example.com/updates --strategy botasaurus
+
+BOTASAURUS_SCRAPER_URL="http://localhost:4010" \\
+html2rss feed my_config.yml --strategy botasaurus
 `}
-  lang="sh"
+lang="bash"
 />
 
 ---
diff --git a/src/content/docs/web-application/guides/setup-for-development.mdx b/src/content/docs/web-application/guides/setup-for-development.mdx
index 61c3f7ab..ecf7eee7 100644
--- a/src/content/docs/web-application/guides/setup-for-development.mdx
+++ b/src/content/docs/web-application/guides/setup-for-development.mdx
@@ -19,26 +19,25 @@ All you need to do is install and run Docker.
 
 # Run the image and name it html2rss-web-dev:
 
-docker run \
- --detach \
- --mount type=bind,source=$(pwd)/config,target=/app/config \
- --name html2rss-web-dev \
- html2rss-web
+docker run \\
+--detach \\
+--mount type=bind,source=$(pwd)/config,target=/app/config \\
+--name html2rss-web-dev \\
+html2rss-web
 
-# Open an interactive TTY with the shell \`sh\`:
+# Open an interactive TTY with the shell:
 
 docker exec -ti html2rss-web-dev sh
 
 # Stop and clean up the container
 
-docker stop html2rss-web-dev && \
- docker rm html2rss-web-dev
+docker stop html2rss-web-dev && docker rm html2rss-web-dev
 
 # Remove the image
 
 docker rmi html2rss-web
 `}
-lang="sh"
+lang="bash"
 />
 
 ### Using installed Ruby
diff --git a/src/content/docs/web-application/index.mdx b/src/content/docs/web-application/index.mdx
index abbc1420..1d8cb2bf 100644
--- a/src/content/docs/web-application/index.mdx
+++ b/src/content/docs/web-application/index.mdx
@@ -38,7 +38,7 @@ The scraping and feed-building engine is provided by the Ruby gem [`html2rss`](h
 Once your instance is running, learn how to use its core features:
 
 - **[Use automatic feed generation](/web-application/guides/use-automatic-feed-generation/)**: create feeds from page URLs
-- **[Use included configs](/web-application/guides/use-included-configs/)**: use the built-in Feed Directory as a fallback
+- **[Use the Feed Directory](/web-application/guides/use-the-feed-directory/)**: use the built-in Feed Directory as a fallback
 - **[Monitoring](/web-application/reference/monitoring/)**: keep your instance healthy
 
 ## For Integrations

From be9f7b83254d82896d4430580e1e117068dc62a0 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <gildesmarais@users.noreply.github.com>
Date: Tue, 11 Aug 2026 11:02:25 +0200
Subject: [PATCH 11/13] Update
 src/content/docs/ruby-gem/guides/advanced-features.mdx

---
 src/content/docs/ruby-gem/guides/advanced-features.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/ruby-gem/guides/advanced-features.mdx b/src/content/docs/ruby-gem/guides/advanced-features.mdx
index 77453a4f..f89cc46c 100644
--- a/src/content/docs/ruby-gem/guides/advanced-features.mdx
+++ b/src/content/docs/ruby-gem/guides/advanced-features.mdx
@@ -124,7 +124,7 @@ You can add custom validation by using post-processors:
       selector: "article"
     title:
       selector: "h2"
-      post_processors:
+      post_process:
         - name: "gsub"
           pattern: "^\\s*$"
           replacement: "Untitled"

From 007901c21316a32f0aea2ec74972bcc39bd5617e Mon Sep 17 00:00:00 2001
From: Gil Desmarais <gildesmarais@users.noreply.github.com>
Date: Tue, 11 Aug 2026 11:02:33 +0200
Subject: [PATCH 12/13] Update
 src/content/docs/ruby-gem/reference/selectors.mdx

---
 src/content/docs/ruby-gem/reference/selectors.mdx | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/content/docs/ruby-gem/reference/selectors.mdx b/src/content/docs/ruby-gem/reference/selectors.mdx
index 6533ec6e..9b4e5578 100644
--- a/src/content/docs/ruby-gem/reference/selectors.mdx
+++ b/src/content/docs/ruby-gem/reference/selectors.mdx
@@ -215,13 +215,13 @@ While you can define any named selector, only the following are used in the fina
 
 Each selector can be configured with the following options:
 
-| Name              | Description                                              |
-| ----------------- | -------------------------------------------------------- |
-| `selector`        | The CSS selector for the target element.                 |
-| `extractor`       | The extractor to use for this selector.                  |
-| `attribute`       | The attribute name (required for `attribute` extractor). |
-| `static`          | The static value (required for `static` extractor).      |
-| `post_processors` | A list of post-processors to apply to the value.         |
+| Name           | Description                                              |
+| -------------- | -------------------------------------------------------- |
+| `selector`     | The CSS selector for the target element.                 |
+| `extractor`    | The extractor to use for this selector.                  |
+| `attribute`    | The attribute name (required for `attribute` extractor). |
+| `static`       | The static value (required for `static` extractor).      |
+| `post_process` | A list of post-processors to apply to the value.         |
 
 ### Extractors
 

From 41e9982a529cc0257e423dfe21289e2d9c664957 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <gildesmarais@users.noreply.github.com>
Date: Tue, 11 Aug 2026 11:02:41 +0200
Subject: [PATCH 13/13] Update src/content/docs/creating-custom-feeds.mdx

---
 src/content/docs/creating-custom-feeds.mdx | 21 ++++++++++-----------
 1 file changed, 10 insertions(+), 11 deletions(-)

diff --git a/src/content/docs/creating-custom-feeds.mdx b/src/content/docs/creating-custom-feeds.mdx
index ae828675..22422ece 100644
--- a/src/content/docs/creating-custom-feeds.mdx
+++ b/src/content/docs/creating-custom-feeds.mdx
@@ -104,17 +104,16 @@ This says: "Find each article, get the title from the h2 anchor, and get the lin
   channel:
     url: https://example.com/blog
     title: My Blog
-
-selectors:
-items:
-selector: "article.post"
-title:
-selector: "h2 a"
-url:
-selector: "h2 a"
-extractor: "href"
-`}
-lang="yaml"
+  selectors:
+    items:
+      selector: "article.post"
+    title:
+      selector: "h2 a"
+    url:
+      selector: "h2 a"
+      extractor: "href"
+  `}
+  lang="yaml"
 />
 
 **Step 3:** Test it with your html2rss-web instance or the [Ruby gem](/ruby-gem/installation/).