From 266f5e19ce440a3683a7e5b9d64454749493912e Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Jul 2025 15:02:17 +0200
Subject: [PATCH 01/17] feat: add contents from html2rss gem readme

Signed-off-by: Gil Desmarais <git@desmarais.de>
---
 about.md                                   |  44 ++++++++
 api-reference.md                           |  55 ++++++++++
 components/html2rss-configs.md             |  23 ----
 components/html2rss-web.md                 |  28 -----
 components/html2rss.md                     |  32 ------
 components/index.md                        |   7 --
 configs/index.html                         |   4 +-
 configuration/auto_source.md               |  68 ++++++++++++
 configuration/channel.md                   |  35 ++++++
 configuration/headers.md                   |  51 +++++++++
 configuration/index.md                     |  24 +++++
 configuration/selectors/extractors.md      |  51 +++++++++
 configuration/selectors/index.md           | 118 +++++++++++++++++++++
 configuration/selectors/post-processors.md |  71 +++++++++++++
 configuration/strategy.md                  |  83 +++++++++++++++
 configuration/stylesheets.md               |  72 +++++++++++++
 contributing.md                            |  52 +++++++--
 examples/advanced-content-extraction.md    |  18 ++++
 examples/custom-http-requests.md           |  14 +++
 examples/dynamic-parameters.md             |  35 ++++++
 examples/handling-dynamic-content.md       |  14 +++
 examples/index.md                          |  30 ++++++
 examples/simple-blog-list.md               |  64 +++++++++++
 examples/styling-rss-feed.md               |  14 +++
 getting-started/index.md                   |  41 +++++++
 getting-started/installation.md            |  72 +++++++++++++
 getting-started/your-first-feed.md         |  65 ++++++++++++
 index.html                                 |  25 -----
 index.md                                   |  69 ++++++++++++
 support/contact.md                         |  36 +++++++
 support/troubleshooting.md                 | 109 +++++++++++++++++++
 31 files changed, 1297 insertions(+), 127 deletions(-)
 create mode 100644 about.md
 create mode 100644 api-reference.md
 delete mode 100644 components/html2rss-configs.md
 delete mode 100644 components/html2rss-web.md
 delete mode 100644 components/html2rss.md
 delete mode 100644 components/index.md
 create mode 100644 configuration/auto_source.md
 create mode 100644 configuration/channel.md
 create mode 100644 configuration/headers.md
 create mode 100644 configuration/index.md
 create mode 100644 configuration/selectors/extractors.md
 create mode 100644 configuration/selectors/index.md
 create mode 100644 configuration/selectors/post-processors.md
 create mode 100644 configuration/strategy.md
 create mode 100644 configuration/stylesheets.md
 create mode 100644 examples/advanced-content-extraction.md
 create mode 100644 examples/custom-http-requests.md
 create mode 100644 examples/dynamic-parameters.md
 create mode 100644 examples/handling-dynamic-content.md
 create mode 100644 examples/index.md
 create mode 100644 examples/simple-blog-list.md
 create mode 100644 examples/styling-rss-feed.md
 create mode 100644 getting-started/index.md
 create mode 100644 getting-started/installation.md
 create mode 100644 getting-started/your-first-feed.md
 delete mode 100644 index.html
 create mode 100644 index.md
 create mode 100644 support/contact.md
 create mode 100644 support/troubleshooting.md

diff --git a/about.md b/about.md
new file mode 100644
index 00000000..8f509a46
--- /dev/null
+++ b/about.md
@@ -0,0 +1,44 @@
+---
+layout: default
+title: About html2rss
+# nav_order: 2
+---
+
+# About html2rss
+
+`html2rss` is an open-source project dedicated to empowering users to take control of their web content consumption. In an age where many websites no longer offer traditional RSS feeds, `html2rss` bridges this gap by providing a robust and flexible solution for converting any HTML content into a structured RSS format.
+
+The project was started in 2018 and has since grown into a suite of tools that help users create and consume RSS feeds.
+
+---
+
+### Our Mission
+
+Our mission is to provide a simple, powerful, and accessible tool that enables individuals and developers to create custom RSS feeds from any web page. We believe in the power of open standards and the freedom to access information on your own terms.
+
+---
+
+### The html2rss Ecosystem
+
+The `html2rss` project is more than just a single tool. It's a collection of tools that work together to provide a complete RSS solution:
+
+- **[`html2rss`](https://github.com/html2rss/html2rss):** The core Ruby gem that provides the main functionality for converting HTML to RSS.
+- **[`html2rss-web`](https://github.com/html2rss/html2rss-web):** A web application that allows you to create and manage your RSS feeds through a user-friendly interface.
+- **[`html2rss-configs`](https://github.com/html2rss/html2rss-configs):** A collection of pre-built feed configs for popular websites, so you can get started quickly.
+
+---
+
+### Project Philosophy
+
+- **User Empowerment:** Give users the tools to customize their web experience.
+- **Simplicity & Power:** Offer an easy-to-use interface with powerful underlying capabilities.
+- **Open Source:** Foster a collaborative environment where the community can contribute and improve the project.
+- **Reliability:** Strive for a stable and dependable tool that consistently delivers.
+
+---
+
+### The Team
+
+`html2rss` is maintained by a dedicated group of volunteers and contributors from around the world. We are passionate about open source and committed to continuously improving the project.
+
+Want to join us? Check out our [Contributing Guide]({{ '/contributing/' | relative_url }})!
diff --git a/api-reference.md b/api-reference.md
new file mode 100644
index 00000000..fc0a4c93
--- /dev/null
+++ b/api-reference.md
@@ -0,0 +1,55 @@
+---
+layout: default
+title: API Reference
+nav_order: 8
+---
+
+# API Reference
+
+This section provides a reference for 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)
+
+---
+
+### Command-Line Interface (CLI)
+
+The `html2rss` executable provides the primary way to interact with the tool from your terminal.
+
+#### `html2rss auto <URL>`
+
+Automatically generates an RSS feed from the provided URL.
+
+- `<URL>` (Required): The URL of the website to generate a feed from.
+
+**Example:**
+
+```bash
+html2rss auto https://unmatchedstyle.com/
+```
+
+#### `html2rss feed <CONFIG_FILE>`
+
+Generates an RSS feed based on the provided YAML configuration file.
+
+- `<CONFIG_FILE>` (Required): Path to your YAML configuration file.
+
+**Examples:**
+
+```bash
+# Generate and print to console
+html2rss feed my_feed.yml
+
+# Generate and save to an XML file
+html2rss feed my_feed.yml > my_feed.xml
+```
+
+#### `html2rss help`
+
+Displays the help message with available commands and options.
+
+#### `html2rss --version`
+
+Displays the currently installed version of `html2rss`.
diff --git a/components/html2rss-configs.md b/components/html2rss-configs.md
deleted file mode 100644
index 89c3ca17..00000000
--- a/components/html2rss-configs.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-layout: default
-parent: Components
-nav_order: 3
-title: html2rss-configs
-description: html2rss-configs is a a growing repository of html2rss feed configs.
-summary: a repository of feed configs
----
-
-{{ page.description }}
-{: .fs-8 }
-
----
-
-The [html2rss-config](https://github.com/html2rss/html2rss-configs) repository contains feed configs. Each feed config contains the instructions for the html2rss gem on how to build the RSS feed. Thus, to create a config, you need write CSS selectors and express them in YAML.
-
-The feed config must reside in a folder named after the fully qualified domain name of the website.
-
-The repository has its own test suite. It automatically tests each config and requires them to adhere to the conventions.
-
-A generator scaffolds a feed config and a test for that config. It gets you started in a breeze and let's you focus on writing the selectors.
-
-[See the project on Github](https://github.com/html2rss/html2rss-configs){: .btn .btn-purple }
diff --git a/components/html2rss-web.md b/components/html2rss-web.md
deleted file mode 100644
index fca49e3a..00000000
--- a/components/html2rss-web.md
+++ /dev/null
@@ -1,28 +0,0 @@
----
-layout: default
-parent: Components
-nav_order: 2
-title: html2rss-web
-description: html2rss-web app is a small application which serves RSS feeds via HTTP.
-summary: serves RSS feeds via HTTP
----
-
-{{ page.description }}
-{: .fs-8 }
-
----
-
-html2rss-web builds and serves RSS feeds via HTTP. It's a small application which serves feeds via HTTP. It uses the _feed configs_ from [html2rss-configs](./html2rss-configs) and expose the _html2rss_ generated feeds via HTTP.
-
-**Generate your own feeds, or start instantly with the included configs.**
-
-- It's deployable without much hassle (also via Docker).
-- It has a file-based application cache to prevent _hammering_ websites
-- It handles with client-side HTTP cache headers.
-
-<p>
-  Everyone can host their own <em>html2rss-web</em> instance.
-  There are [public instances](https://github.com/html2rss/html2rss-web/wiki/Instances) for those who can't.
-</p>
-
-[See the project on Github](https://github.com/html2rss/html2rss-web){: .btn .btn-purple }
diff --git a/components/html2rss.md b/components/html2rss.md
deleted file mode 100644
index 084c9ca2..00000000
--- a/components/html2rss.md
+++ /dev/null
@@ -1,32 +0,0 @@
----
-layout: default
-parent: Components
-nav_order: 1
-title: html2rss gem
-description: html2rss build RSS 2.0 feeds from websites (and JSON APIs) with a few CSS selectors.
-summary: a Ruby gem to build RSS 2.0 feeds
----
-
-{{ page.description }}
-{: .fs-8 }
-
----
-
-The [html2rss gem](https://rubygems.org/gems/html2rss) generates a Ruby RSS object from a _feed config_. It does so by scraping and extracting the website.
-
-Scraping involves a tad more than just selecting an HTML element's text contents.
-
-- You want to sanitize HTML.
-- You might find useful information in a `data` attribute in the page's source.
-- You need to convert relative URLs to absolute ones.
-- You want to parse dates & times in the publishers' time zone.
-- Maybe the website is a JSON API and you want that response converted to a RSS feed?
-- You might need to send requests with Authorization or Cookie HTTP headers.
-- You want to scrape several syntactically equal pages on one website without duplicating the configs.
-- You want to create a custom item description from other attributes.
-
-The documentation covers everything the gem is capable of. If you want to dive deeper, read the [gem's README](https://github.com/html2rss/html2rss/blob/master/README.md) or check [the YARD Docs](https://www.rubydoc.info/gems/html2rss).
-
-The gem's code is automatically tested. There's also code documentation for the API, usually with examples. However, looking inside the test suite to find to find more complex examples is recommended.
-
-[See the project on Github](https://github.com/html2rss/html2rss){: .btn .btn-purple }
diff --git a/components/index.md b/components/index.md
deleted file mode 100644
index 17a1348a..00000000
--- a/components/index.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-layout: default
-title: Components
-nav_order: 3
-has_children: true
-has_toc: true
----
diff --git a/configs/index.html b/configs/index.html
index f4c6a6af..a762539e 100644
--- a/configs/index.html
+++ b/configs/index.html
@@ -1,8 +1,8 @@
 ---
 layout: default
-title: All feeds
+title: Ready-to-use configs
 noindex: true
-nav_order: 1
+# nav_order: 1
 ---
 
 <noscript>
diff --git a/configuration/auto_source.md b/configuration/auto_source.md
new file mode 100644
index 00000000..b0515f3d
--- /dev/null
+++ b/configuration/auto_source.md
@@ -0,0 +1,68 @@
+---
+layout: default
+title: Auto Source
+nav_order: 4
+parent: Configuration
+---
+
+# `auto_source`
+
+The `auto_source` scraper is the easiest way to create a feed. It intelligently finds items on a page without requiring you to specify CSS selectors.
+
+You can enable it in your YAML config like this:
+
+```yaml
+channel:
+  url: https://example.com
+auto_source: {}
+```
+
+---
+
+## How it Works
+
+The `auto_source` scraper uses a series of strategies to find content:
+
+1.  **`schema`:** It looks for structured data in the form of `<script type="json/ld">` tags. Many websites use this to provide machine-readable information about their content, often following the [Schema.org](https://schema.org/) standard.
+2.  **`semantic_html`:** It searches for semantic HTML5 tags like `<article>`, `<main>`, and `<section>`. These tags are often used to define the main content of a page.
+3.  **`html`:** As a last resort, it analyzes the entire HTML structure to find frequently occurring selectors that are likely to contain the main content.
+
+---
+
+## Fine-Tuning `auto_source`
+
+You can customize the behavior of the `auto_source` scraper to improve its accuracy.
+
+### Scraper Options
+
+You can enable or disable specific scrapers and adjust their settings.
+
+```yaml
+auto_source:
+  scraper:
+    schema:
+      enabled: false # default: true
+    semantic_html:
+      enabled: false # default: true
+    html:
+      enabled: true
+      minimum_selector_frequency: 3 # default: 2
+      use_top_selectors: 3 # default: 5
+```
+
+- `minimum_selector_frequency`: The minimum number of times a selector must appear to be considered a candidate for the main content.
+- `use_top_selectors`: The number of top candidate selectors to consider.
+
+### Cleanup Options
+
+You can also clean up the results to remove unwanted items.
+
+```yaml
+auto_source:
+  cleanup:
+    keep_different_domain: false # default: true
+    min_words_title: 4 # default: 3
+```
+
+- `keep_different_domain`: Whether to keep items that link to a different domain.
+- `min_words_title`: The minimum number of words a title must have to be included.
diff --git a/configuration/channel.md b/configuration/channel.md
new file mode 100644
index 00000000..47de9e1f
--- /dev/null
+++ b/configuration/channel.md
@@ -0,0 +1,35 @@
+---
+layout: default
+title: Channel
+nav_order: 1
+parent: Configuration
+---
+
+# `channel`
+
+The `channel` key contains information about the RSS feed itself, such as its title, URL, and description.
+
+```yaml
+channel:
+  url: https://example.com
+  title: "My Custom Feed"
+  description: "A feed of the latest news from Example.com"
+  author: "jane.doe@example.com (Jane Doe)"
+  ttl: 60
+  language: "en-us"
+  time_zone: "Europe/Berlin"
+```
+
+---
+
+## Channel Options
+
+| Attribute     | Required     | Type    | Default        | Remark                                                                                                                                  |
+| :------------ | :----------- | :------ | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
+| `url`         | **Required** | String  |                | The URL of the website to scrape.                                                                                                       |
+| `title`       | Optional     | String  | Auto-generated | The title of the RSS feed.                                                                                                              |
+| `description` | Optional     | String  | Auto-generated | Retrieved from meta description tags.                                                                                                   |
+| `author`      | Optional     | String  | Blank          | Format: `email (Name)`.                                                                                                                 |
+| `ttl`         | Optional     | Integer | Auto-generated | Time to live in minutes. `html2rss` will use the `max-age` from the response headers if available, otherwise it will default to `360`.  |
+| `language`    | Optional     | String  | Auto-generated | Determined by the `lang` attribute of the `<html>` tag.                                                                                 |
+| `time_zone`   | Optional     | String  | `'UTC'`        | The time zone to use for parsing dates. See a [list of valid time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). |
diff --git a/configuration/headers.md b/configuration/headers.md
new file mode 100644
index 00000000..8b1720ac
--- /dev/null
+++ b/configuration/headers.md
@@ -0,0 +1,51 @@
+---
+layout: default
+title: Headers
+nav_order: 1
+parent: Configuration
+---
+
+# `headers`
+
+The `headers` key allows you to set custom HTTP headers for your requests. This is useful for accessing protected content or interacting with APIs.
+
+```yaml
+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"
+  Authorization: "Bearer YOUR_TOKEN"
+```
+
+You can also set headers for APIs that require authorization or custom headers.
+
+Dynamic parameters can be used in headers to pass values at runtime. See [Advanced Topics](/configuration/advanced-topics/) for more details.
+
+## Example Configuration
+
+This example demonstrates how to add custom HTTP headers to your feed request:
+
+```yaml
+channel:
+  url: https://example.com/protected-content
+  headers:
+    User-Agent: "Mozilla/5.0 (compatible; html2rss/1.0)"
+    Authorization: "Bearer your_api_token_here"
+selectors:
+  items:
+    selector: ".article"
+  title:
+    selector: "h2.title"
+  url:
+    selector: "h2.title a"
+    extractor: "href"
+  description:
+    selector: ".summary"
+```
+
+### Explanation
+
+- **`channel.headers`**: Defines custom HTTP headers to include in the request.
+- **`User-Agent`**: Some websites require a specific user agent string.
+- **`Authorization`**: Example of an API token for protected content.
+- The rest of the configuration extracts articles as usual.
+
+Use this configuration to access content that requires authentication or specific headers.
diff --git a/configuration/index.md b/configuration/index.md
new file mode 100644
index 00000000..4b2fb072
--- /dev/null
+++ b/configuration/index.md
@@ -0,0 +1,24 @@
+---
+layout: default
+title: Configuration
+nav_order: 4
+has_children: true
+---
+
+# Configuration
+
+While the `html2rss auto` command is a great starting point, you'll often need to create a YAML configuration file to get the perfect RSS feed. A configuration file gives you fine-grained control over every aspect of the feed generation process.
+
+This section provides a comprehensive guide to all the configuration options available in `html2rss`.
+
+## Configuration Topics
+
+- [**Auto Source**]({{ '/configuration/auto_source/' | relative_url }}): The easiest way to create a feed, with minimal configuration.
+- [**Channel**]({{ '/configuration/channel/' | relative_url }}): Customize the metadata of your RSS feed.
+- [**Selectors**]({{ '/configuration/selectors/' | relative_url }}): Use CSS selectors to extract content with precision.
+- [**Extractors**]({{ '/configuration/selectors/extractors/' | relative_url }}): Specify how to extract information from HTML elements.
+- [**Post Processors**]({{ '/configuration/selectors/post-processors/' | relative_url }}): Manipulate the extracted data to get it just right.
+- [**Strategy**]({{ '/configuration/strategy/' | relative_url }}): Define how html2rss fetches website content, including JavaScript rendering options.
+- [**Headers**]({{ '/configuration/headers/' | relative_url }}): Set custom HTTP headers for requests, useful for APIs and authorization.
+- [**Stylesheets**]({{ '/configuration/stylesheets/' | relative_url }}): Add CSS or XSLT stylesheets to style your RSS feed in browsers.
+- [**Advanced Topics**]({{ '/configuration/advanced-topics/' | relative_url }}): Learn about advanced features like strategies, custom headers, and dynamic parameters.
diff --git a/configuration/selectors/extractors.md b/configuration/selectors/extractors.md
new file mode 100644
index 00000000..27c10622
--- /dev/null
+++ b/configuration/selectors/extractors.md
@@ -0,0 +1,51 @@
+---
+layout: default
+title: Extractors
+parent: Selectors
+---
+
+# Extractors
+
+Extractors help with extracting information from the selected HTML element. You specify the extractor to use on a selector.
+
+```yaml
+selectors:
+  url:
+    selector: "a"
+    extractor: "href"
+```
+
+---
+
+## Available Extractors
+
+- **`text`** (default): Returns the element's inner text.
+- **`html`**: Returns the element's outer HTML.
+- **`href`**: Returns a URL from the element's `href` attribute and corrects relative URLs to absolute ones.
+- **`attribute`**: Returns the value of an element's attribute. You must specify the `attribute` name.
+- **`static`**: Returns a configured static value. You must specify the `value`.
+
+---
+
+## Extractor Examples
+
+### `attribute`
+
+```yaml
+selectors:
+  image:
+    selector: "img"
+    extractor: "attribute"
+    attribute: "src"
+```
+
+### `static`
+
+```yaml
+selectors:
+  author:
+    extractor: "static"
+    value: "John Doe"
+```
+
+For a full list of extractors and their options, please refer to the [official YARD documentation](https://www.rubydoc.info/gems/html2rss/Html2rss/Selectors/Extractors).
diff --git a/configuration/selectors/index.md b/configuration/selectors/index.md
new file mode 100644
index 00000000..6dd01735
--- /dev/null
+++ b/configuration/selectors/index.md
@@ -0,0 +1,118 @@
+---
+layout: default
+title: Selectors
+nav_order: 5
+parent: Configuration
+---
+
+# `selectors`
+
+The `selectors` scraper gives you full control over the content extraction process by using CSS selectors.
+
+To build a valid RSS 2.0 item, you need at least a `title` or a `description` in your item.
+
+---
+
+## `items`
+
+The `items` selector is a required selector that defines the collection of HTML elements from which the RSS feed items are built.
+
+```yaml
+channel:
+  url: "https://example.com"
+selectors:
+  items:
+    selector: ".article"
+  title:
+    selector: "h1"
+```
+
+### Item Enhancement
+
+`html2rss` automatically enhances each item by trying to find the `title`, `url`, and `image`. You can disable this behavior by setting `enhance: false` on the `items` selector.
+
+```yaml
+selectors:
+  items:
+    selector: ".article"
+    enhance: false
+```
+
+---
+
+## Selectors
+
+The following selectors can be used to extract content for the RSS feed:
+
+| RSS 2.0 tag   | Name in `html2rss` | Remark                                    |
+| :------------ | :----------------- | :---------------------------------------- |
+| `title`       | `title`            |                                           |
+| `description` | `description`      | Will be sanitized when it contains HTML.  |
+| `link`        | `url`              | A URL.                                    |
+| `author`      | `author`           |                                           |
+| `category`    | `categories`       | See notes below.                          |
+| `guid`        | `guid`             | Generated automatically. See notes below. |
+| `enclosure`   | `enclosure`        | See notes below.                          |
+| `pubDate`     | `published_at`     | An instance of `Time`.                    |
+| `comments`    | `comments`         | A URL.                                    |
+
+---
+
+## Selector Options
+
+Each selector can have the following attributes:
+
+| Name           | Value                                                                                                   |
+| :------------- | :------------------------------------------------------------------------------------------------------ |
+| `selector`     | The CSS selector to select the element with the information.                                            |
+| `extractor`    | The name of the extractor to use. See [Extractors](/configuration/selectors/extractors/).               |
+| `post_process` | An array of post processors to apply. See [Post Processors](/configuration/selectors/post-processors/). |
+
+---
+
+## Categories
+
+The `categories` selector takes an array of selector names. The value of each of those selectors will become a `<category>` on the RSS item.
+
+```yaml
+selectors:
+  genre:
+    selector: ".genre"
+  branch:
+    selector: ".branch"
+  categories:
+    - genre
+    - branch
+```
+
+---
+
+## Custom GUID
+
+By default, `html2rss` generates a stable GUID automatically. If this is not stable, you can choose from which attributes the GUID will be built.
+
+```yaml
+selectors:
+  title:
+    selector: "h1"
+  url:
+    selector: "a"
+    extractor: "href"
+  guid:
+    - url
+```
+
+---
+
+## Enclosure
+
+An enclosure can be any file, e.g., an image, audio, or video file. The `enclosure` selector needs to return a URL of the content to enclose.
+
+```yaml
+selectors:
+  enclosure:
+    selector: "audio"
+    extractor: "attribute"
+    attribute: "src"
+    content_type: "audio/mp3"
+```
diff --git a/configuration/selectors/post-processors.md b/configuration/selectors/post-processors.md
new file mode 100644
index 00000000..fabf8b54
--- /dev/null
+++ b/configuration/selectors/post-processors.md
@@ -0,0 +1,71 @@
+---
+layout: default
+title: Post Processors
+parent: Selectors
+---
+
+# Post Processors
+
+Post processors can be used to manipulate the extracted information. You can specify one or more post processors, and they will be applied in the order they are listed.
+
+```yaml
+selectors:
+  title:
+    selector: "h1"
+    post_process:
+      - name: "gsub"
+        pattern: "foo"
+        replacement: "bar"
+      - name: "substring"
+        start: 0
+        length: 10
+```
+
+---
+
+## Available Post Processors
+
+- **`gsub`**: Performs a global substitution on a string.
+- **`html_to_markdown`**: Converts HTML to Markdown.
+- **`markdown_to_html`**: Converts Markdown to HTML.
+- **`parse_time`**: Parses a string containing a time.
+- **`parse_uri`**: Parses a string as a URL.
+- **`sanitize_html`**: Strips unsafe and unneeded HTML.
+- **`substring`**: Extracts a part of a string.
+- **`template`**: Creates a new string from a template.
+
+⚠️ Always use the `sanitize_html` post processor for HTML content. Never trust the internet! ⚠️
+
+---
+
+## Post Processor Examples
+
+### `gsub`
+
+```yaml
+post_process:
+  - name: "gsub"
+    pattern: "foo"
+    replacement: "bar"
+```
+
+### `template`
+
+The `template` post processor allows you to create a new string from a template, using values from other selectors.
+
+```yaml
+selectors:
+  price:
+    selector: ".price"
+  description:
+    selector: ".section"
+    post_process:
+      - name: template
+        string: |
+          # %{self}
+
+          Price: %{price}
+      - name: markdown_to_html
+```
+
+For a full list of post processors and their options, please refer to the [official YARD documentation](https://www.rubydoc.info/gems/html2rss/).
diff --git a/configuration/strategy.md b/configuration/strategy.md
new file mode 100644
index 00000000..6e01896f
--- /dev/null
+++ b/configuration/strategy.md
@@ -0,0 +1,83 @@
+---
+layout: default
+title: Strategy
+nav_order: 2
+parent: Configuration
+---
+
+# `strategy`
+
+The `strategy` key defines how `html2rss` fetches the website's content.
+
+- **`faraday`** (default): Makes a simple HTTP request and does not execute JavaScript. It's fast and works for many websites.
+- **`browserless`**: Uses a headless Chrome browser to render the website. This is essential for JavaScript-heavy websites that build their HTML on the client side.
+
+## browserless
+
+### Requirements
+
+To use the `browserless` strategy, you need to have a [Browserless.io](https://www.browserless.io/) instance running.
+
+```yaml
+strategy: browserless
+```
+
+You can use _Browserless.io_ to run a headless 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
+```
+
+### Usage examples CLI
+
+To make html2rss use your instance, specify the `browserless` strategy.
+
+```sh
+# auto:
+BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000" BROWSERLESS_IO_API_TOKEN="6R0W53R135510" \
+  html2rss auto --strategy=browserless https://example.com
+
+# feed:
+BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000" BROWSERLESS_IO_API_TOKEN="6R0W53R135510" \
+  html2rss feed --strategy=browserless the_the_config.yml
+```
+
+> [!TIP]
+> When running locally with commands from above, you can skip setting the environment variables, as they are aligned with the default values from above example.
+
+### Usage examples in feed config
+
+In your config, set `strategy: browserless`.
+
+```yml
+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"
+channel:
+  url: https://www.imdb.com/user/ur67728460/ratings
+  ttl: 1440
+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}"
+  url:
+    selector: "a.ipc-title-link-wrapper"
+    extractor: "href"
+  user_rating:
+    selector: "[data-testid='ratingGroup--other-user-rating'] > .ipc-rating-star--rating"
+```
diff --git a/configuration/stylesheets.md b/configuration/stylesheets.md
new file mode 100644
index 00000000..747fef7d
--- /dev/null
+++ b/configuration/stylesheets.md
@@ -0,0 +1,72 @@
+---
+layout: default
+title: Stylesheets
+nav_order: 3
+parent: Configuration
+---
+
+# `stylesheets`
+
+The `stylesheets` key allows you to add CSS or XSLT stylesheets to your RSS feed to improve its appearance in a web browser.
+
+```yaml
+stylesheets:
+  - href: "/relative/base/path/to/style.xls"
+    media: "all"
+    type: "text/xsl"
+  - href: "http://example.com/rss.css"
+    media: "all"
+    type: "text/css"
+```
+
+---
+
+### Explanation
+
+You can add plain CSS stylesheets or XSLT (eXtensible Stylesheet Language Transformations) to style your RSS feed when viewed in a web browser.
+
+- CSS stylesheets use element selectors to apply styles.
+- XSLT allows you to use HTML templates and add JavaScript or external resources for advanced styling.
+
+---
+
+### Examples
+
+#### Ruby example
+
+```ruby
+Html2rss.feed(
+  stylesheets: [
+    {
+      href: '/relative/base/path/to/style.xsl', media: :all, type: 'text/xsl'
+    },
+    {
+      href: 'http://example.com/rss.css', media: :all, type: 'text/css'
+    }
+  ],
+  channel: {},
+  selectors: {}
+)
+```
+
+#### YAML example
+
+```yaml
+stylesheets:
+  - href: "/relative/base/path/to/style.xsl"
+    media: "all"
+    type: "text/xsl"
+  - href: "http://example.com/rss.css"
+    media: "all"
+    type: "text/css"
+feeds:
+  # your feed configs here
+```
+
+---
+
+### Further Reading
+
+- [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)
diff --git a/contributing.md b/contributing.md
index a608129d..df88d159 100644
--- a/contributing.md
+++ b/contributing.md
@@ -4,22 +4,54 @@ title: Contributing
 nav_order: 10
 ---
 
-There are many ways to contribute. Contributions are very welcome!
+# Contributing to html2rss
 
-## Create a feed config
+We're thrilled that you're interested in contributing to `html2rss`! There are many ways to get involved, and we welcome contributions of all kinds.
 
-Are you missing an RSS for a site? Create your config and add make it available in the ecosystem. [It's easy, just have a look and try it out!](https://github.com/html2rss/html2rss-configs)
+---
+
+## Code of Conduct
+
+Before you begin, please read our [Code of Conduct](https://github.com/html2rss/.github/blob/main/CODE_OF_CONDUCT.md). We expect all contributors to adhere to this code to ensure that our community is a welcoming and inclusive space for everyone.
+
+---
+
+## How to Contribute
+
+Here are some of the ways you can contribute to the `html2rss` project:
+
+### 1. Create a Feed Config
+
+Are you missing an RSS feed for a website? You can create your own feed config and share it with the community. It's a great way to get started with `html2rss` and help other users.
 
-## Improve this website
+[**Learn how to create a feed config**](https://github.com/html2rss/html2rss-configs)
 
-This website is build with Jekyll and Github Actions. [Find the source code here.](https://github.com/html2rss/html2rss.github.io)
+### 2. Improve this Website
 
-## Host your own public instance
+This website is built with Jekyll and is hosted on GitHub Pages. If you have any ideas for improving the documentation or the design, we'd love to hear from you.
 
-The [html2rss-web project](https://github.com/html2rss/html2rss-web) is a rolling release web application which comes with the latest html2rss-configs build in.
+[**Find the source code on GitHub**](https://github.com/html2rss/html2rss.github.io)
 
-Setup and maintain your instance. Do not forget to add your instance to [the instances list in the wiki](https://github.com/html2rss/html2rss-web/wiki/Instances) so that others can start using it.
+### 3. Host a Public Instance
 
-## Improve the html2rss gem
+The [`html2rss-web`](https://github.com/html2rss/html2rss-web) project is a web application that allows you to create and manage your RSS feeds through a user-friendly interface. You can host your own public instance to help other users create feeds.
+
+[**Learn how to host a public instance**](https://github.com/html2rss/html2rss-web/wiki/Instances)
+
+### 4. Improve the `html2rss` Gem
+
+Are you a Ruby developer? You can help us improve the core `html2rss` gem. Whether you're fixing a bug, adding a new feature, or improving the documentation, your contributions are welcome.
+
+[**Check out the repository on GitHub**](https://github.com/html2rss/html2rss)
+
+### 5. Report Bugs and Request Features
+
+If you've found a bug or have an idea for a new feature, please let us know! You can open an issue on the appropriate GitHub repository.
+
+- [**`html2rss` issues**](https://github.com/html2rss/html2rss/issues)
+- [**`html2rss-web` issues**](https://github.com/html2rss/html2rss-web/issues)
+- [**`html2rss-configs` issues**](https://github.com/html2rss/html2rss-configs/issues)
+
+---
 
-Are you missing a feature in the [html2rss gem](https://github.com/html2rss/html2rss)? Did you find a bug? Head to the [repository on Github](https://github.com/html2rss/html2rss) and start working on it.
+We appreciate your interest in contributing to `html2rss`!
diff --git a/examples/advanced-content-extraction.md b/examples/advanced-content-extraction.md
new file mode 100644
index 00000000..16478124
--- /dev/null
+++ b/examples/advanced-content-extraction.md
@@ -0,0 +1,18 @@
+---
+layout: default
+title: Advanced Content Extraction with Selectors
+nav_order: 10
+parent: Examples
+---
+
+# Advanced Content Extraction with Selectors
+
+While basic selectors are straightforward, you can achieve very precise content extraction by combining selectors with different extractors and post-processors.
+
+## Extractors
+
+Learn how to extract specific attributes (like `src` for images) or static values. See [Extractors](/configuration/selectors/extractors/).
+
+## Post Processors
+
+Manipulate extracted text, sanitize HTML, convert Markdown, or apply custom logic. See [Post Processors](/configuration/selectors/post-processors/).
diff --git a/examples/custom-http-requests.md b/examples/custom-http-requests.md
new file mode 100644
index 00000000..41c66139
--- /dev/null
+++ b/examples/custom-http-requests.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: Customizing HTTP Requests
+nav_order: 8
+parent: Examples
+---
+
+# Customizing HTTP Requests
+
+You might need to send custom HTTP headers (e.g., `User-Agent`, `Authorization`) to access certain content or interact with APIs.
+
+## Solution
+
+Configure [custom HTTP headers](/configuration/headers) in your feed configuration.
diff --git a/examples/dynamic-parameters.md b/examples/dynamic-parameters.md
new file mode 100644
index 00000000..5256c17e
--- /dev/null
+++ b/examples/dynamic-parameters.md
@@ -0,0 +1,35 @@
+---
+layout: default
+title: Dynamic Parameters in URLs and Headers
+nav_order: 9
+parent: Examples
+---
+
+# Dynamic Parameters in URLs and Headers
+
+For websites with similar structures but varying content based on a parameter in the URL or headers, you can use dynamic parameters.
+
+## Solution
+
+You can add dynamic parameters to the `channel` and `headers` values. This is useful for creating feeds from structurally similar pages with different URLs.
+
+```yaml
+channel:
+  url: "http://domainname.tld/whatever/%<id>s.html"
+headers:
+  X-Something: "%<foo>s"
+```
+
+You can then pass the values for these parameters when you run `html2rss`:
+
+```bash
+html2rss feed the_feed_config.yml --params id:42 foo:bar
+```
+
+---
+
+## Explanation
+
+- The `%<param>s` syntax in the URL and headers is a placeholder for dynamic parameters.
+- You provide the actual values for these parameters at runtime using the `--params` option.
+- This allows you to reuse the same feed configuration for multiple similar pages or APIs.
diff --git a/examples/handling-dynamic-content.md b/examples/handling-dynamic-content.md
new file mode 100644
index 00000000..fe3fd4d3
--- /dev/null
+++ b/examples/handling-dynamic-content.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: Handling Dynamic Content and JavaScript
+nav_order: 7
+parent: Examples
+---
+
+# Handling Dynamic Content and JavaScript
+
+Some websites load their content dynamically using JavaScript. The default `html2rss` strategy might not see this content.
+
+## Solution
+
+Use the [`browserless` strategy](/configuration/strategy) to render JavaScript-heavy websites with a headless browser.
diff --git a/examples/index.md b/examples/index.md
new file mode 100644
index 00000000..909ff2f3
--- /dev/null
+++ b/examples/index.md
@@ -0,0 +1,30 @@
+---
+layout: default
+title: Examples
+nav_order: 6
+has_children: true
+---
+
+# Examples: Practical `html2rss` Configurations
+
+This section provides a collection of ready-to-use `html2rss` configuration examples for various popular websites and common use cases. These examples demonstrate how to tackle different HTML structures and content types.
+
+Use these as a starting point, modify them to fit your specific needs, or get inspiration for building your own custom feeds.
+
+---
+
+### How to Use an Example
+
+1.  **Copy the YAML:** Copy the entire YAML configuration block for the example you're interested in.
+2.  **Save as `.yml`:** Save the copied content into a file, e.g., `my-example.yml`.
+3.  **Generate the Feed:** Run `html2rss` from your terminal:
+    ```bash
+    html2rss feed my-example.yml > my-example.xml
+    ```
+4.  **Enjoy!** Open `my-example.xml` in your favorite RSS reader.
+
+---
+
+### Contribute Your Own Examples!
+
+Have you created a useful `html2rss` configuration? We encourage you to share it with the community by contributing to the [`html2rss-configs`](https://github.com/html2rss/html2rss-configs) repository.
diff --git a/examples/simple-blog-list.md b/examples/simple-blog-list.md
new file mode 100644
index 00000000..2126a7d6
--- /dev/null
+++ b/examples/simple-blog-list.md
@@ -0,0 +1,64 @@
+---
+layout: default
+title: Simple Blog List
+parent: Examples
+nav_order: 1
+---
+
+# Example: Scraping a Simple Blog List
+
+This example demonstrates how to create a feed from a typical blog that has a list of articles on its homepage.
+
+---
+
+## The Goal
+
+We want to create an RSS feed that contains the title, link, and summary of each article on the blog.
+
+---
+
+## The HTML
+
+Here's a simplified view of the HTML structure we're targeting. The key is to find a container element that wraps each blog post (in this case, `.post-item`) and then find the selectors for the title, link, and summary within that container.
+
+```html
+<div class="posts">
+  <div class="post-item">
+    <h2 class="post-title"><a href="/blog/post-1">First Post Title</a></h2>
+    <p class="post-summary">Summary of the first post...</p>
+  </div>
+  <div class="post-item">
+    <h2 class="post-title"><a href="/blog/post-2">Second Post Title</a></h2>
+    <p class="post-summary">Summary of the second post...</p>
+  </div>
+</div>
+```
+
+---
+
+## The Configuration
+
+This configuration uses the `selectors` scraper to precisely extract the content we want.
+
+```yaml
+channel:
+  url: https://example.com/blog
+selectors:
+  items:
+    selector: ".post-item"
+  title:
+    selector: ".post-title a"
+  url:
+    selector: ".post-title a"
+    extractor: "href"
+  description:
+    selector: ".post-summary"
+```
+
+### Configuration Breakdown
+
+- **`items.selector: ".post-item"`**: This is the most important selector. It tells `html2rss` that every element with the class `post-item` is a single item in the RSS feed.
+- **`title.selector: ".post-title a"`**: Within each `.post-item`, this finds the `<a>` tag inside the element with the class `post-title`.
+- **`url.selector: ".post-title a"`**: This finds the same `<a>` tag.
+- **`url.extractor: "href"`**: This extracts the URL from the `href` attribute of the `<a>` tag.
+- **`description.selector: ".post-summary"`**: This finds the element with the class `post-summary`.
diff --git a/examples/styling-rss-feed.md b/examples/styling-rss-feed.md
new file mode 100644
index 00000000..0700eeff
--- /dev/null
+++ b/examples/styling-rss-feed.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: Styling Your RSS Feed
+nav_order: 11
+parent: Examples
+---
+
+# Styling Your RSS Feed
+
+You can make your RSS feed look good in a web browser by attaching stylesheets.
+
+## Solution
+
+Add [stylesheets](/configuration/stylesheets) to your feed configuration.
diff --git a/getting-started/index.md b/getting-started/index.md
new file mode 100644
index 00000000..1ad6c58e
--- /dev/null
+++ b/getting-started/index.md
@@ -0,0 +1,41 @@
+---
+layout: default
+title: Getting Started
+nav_order: 3
+has_children: true
+---
+
+# Getting Started with html2rss
+
+Welcome to the `html2rss` quick start guide! This section will walk you through the essential steps to get `html2rss` up and running and create your very first custom RSS feed.
+
+We've designed this guide to be as straightforward as possible, whether you're a seasoned developer or new to web scraping.
+
+---
+
+## Where to Start
+
+We recommend starting with the installation guide to set up `html2rss` on your system. Once installed, proceed to our step-by-step guide to creating your first feed. It covers everything from the simplest "no-config" method to creating a custom feed with CSS selectors.
+
+[**⚙️ Start with Installation**]({{ '/getting-started/installation/' | relative_url }})
+
+[**🚀 Then, move to "Your First Feed" Guide**]({{ '/getting-started/your-first-feed/' | relative_url }})
+
+---
+
+## Automatic Generation (auto_source)
+
+For those looking for the quickest way to get started, `html2rss` offers an automatic method (`auto_source`) that intelligently scrapes a page to find content. This approach requires minimal setup and is perfect for a rapid start.
+
+[**⚡️ Learn about the "Automatic Generation" Method**]({{ '/getting-started/your-first-feed/#step-1-the-no-config-method-auto' | relative_url }})
+
+---
+
+## Other Topics
+
+- [**Handling Dynamic Content and JavaScript**]({{ '/examples/handling-dynamic-content/' | relative_url }}): Learn how to handle JavaScript-heavy websites.
+- [**Customizing HTTP Requests**]({{ '/examples/custom-http-requests/' | relative_url }}): How to send custom HTTP headers.
+- [**Dynamic Parameters in URLs and Headers**]({{ '/examples/dynamic-parameters/' | relative_url }}): Use dynamic parameters in URLs and headers.
+- [**Advanced Content Extraction with Selectors**]({{ '/examples/advanced-content-extraction/' | relative_url }}): Precise content extraction techniques.
+- [**Styling Your RSS Feed**]({{ '/examples/styling-rss-feed/' | relative_url }}): Add stylesheets to your RSS feed.
+- [**Debugging Your Configuration**]({{ '/examples/debugging-configuration/' | relative_url }}): Debug your feed configuration effectively.
diff --git a/getting-started/installation.md b/getting-started/installation.md
new file mode 100644
index 00000000..defc5c2e
--- /dev/null
+++ b/getting-started/installation.md
@@ -0,0 +1,72 @@
+---
+layout: default
+title: Installation
+parent: Getting Started
+nav_order: 1
+---
+
+# Installation
+
+This guide will walk you through the process of installing html2rss on your system. html2rss can be installed in several ways, depending on your preferred method and environment.
+
+---
+
+### Prerequisites
+
+- **Ruby:** html2rss is built with Ruby. Ensure you have Ruby installed (version 3.3 or higher recommended). You can check your Ruby version by running `ruby -v` in your terminal. If you don't have Ruby, visit [ruby-lang.org](https://www.ruby-lang.org/en/documentation/installation/) for installation instructions.
+- **Bundler (Recommended):** Bundler is a Ruby gem that manages your application's dependencies. It's highly recommended for a smooth installation. Install it with `gem install bundler`.
+
+---
+
+### Method 1: Gem Installation (Recommended for CLI Usage)
+
+The simplest way to get html2rss for command-line usage is to install it as a Ruby gem.
+
+```bash
+gem install html2rss
+```
+
+After installation, you should be able to run `html2rss --version` to confirm it's working.
+
+---
+
+### Method 2: Using a Gemfile (For Ruby Projects)
+
+If you're integrating html2rss into an existing Ruby project, add it to your `Gemfile`:
+
+```ruby
+# Gemfile
+gem 'html2rss'
+```
+
+Then, run `bundle install` in your project directory.
+
+---
+
+### Method 3: Docker (For Containerized Environments)
+
+For a more isolated and reproducible environment, you can use the official html2rss Docker image.
+
+```bash
+docker pull html2rss/html2rss
+```
+
+You can then run html2rss commands within a Docker container. Refer to the [Docker Hub page](https://hub.docker.com/r/html2rss/html2rss) for detailed usage.
+
+---
+
+### Verifying Installation
+
+To ensure html2rss is installed correctly, open your terminal and run:
+
+```bash
+html2rss --version
+```
+
+You should see the installed version number. If you encounter any issues, please refer to the [Troubleshooting Guide]({{ "/support/troubleshooting/" | relative_url }}).
+
+---
+
+### Next Steps
+
+Now that html2rss is installed, let's create your [first RSS feed]({{ "/getting-started/your-first-feed/" | relative_url }})!
diff --git a/getting-started/your-first-feed.md b/getting-started/your-first-feed.md
new file mode 100644
index 00000000..28e65ba5
--- /dev/null
+++ b/getting-started/your-first-feed.md
@@ -0,0 +1,65 @@
+---
+layout: default
+title: Your First Feed
+nav_order: 1
+parent: Getting Started
+---
+
+# Your First Feed: A Step-by-Step Guide
+
+Welcome to `html2rss`! This guide will walk you through creating your first RSS feed. We'll start with the easiest method and gradually introduce more powerful options.
+
+---
+
+## Step 1: The "No-Config" Method (`auto`)
+
+The easiest way to create a feed is with the `auto` command. It requires no configuration file and intelligently scrapes the page to find content.
+
+Open your terminal and run this command:
+
+```bash
+html2rss auto https://unmatchedstyle.com/
+```
+
+`html2rss` will analyze the website and generate an RSS feed for you, printing it directly to the console. This is a great way to see if `html2rss` can automatically handle your target website.
+
+**Is the result not quite right?** Let's move to the next step.
+
+---
+
+## Step 2: The "Full Control" Method (`selectors`)
+
+When you need to extract content with precision, the `selectors` scraper is the tool for the job. This method gives you complete control over what content is included in your feed by using CSS selectors.
+
+Let's create a feed for Stack Overflow's "Hot Network Questions".
+
+1.  **Create a file** named `stackoverflow.yml`.
+2.  **Add the following content:**
+
+    ```yaml
+    channel:
+      url: https://stackoverflow.com/questions
+    selectors:
+      items:
+        selector: "#hot-network-questions > ul > li"
+      title:
+        selector: "a"
+      url:
+        selector: "a"
+        extractor: "href"
+    ```
+
+3.  **Run the `feed` command:**
+
+    ```bash
+    html2rss feed stackoverflow.yml
+    ```
+
+This configuration tells `html2rss`:
+
+- The main container for all items is `<ul id="hot-network-questions">`.
+- Each item is inside a `<li>` tag.
+- The `title` of each item is the text of the `<a>` tag.
+- The `url` of each item is the `href` attribute of the `<a>` tag.
+
+This is just the beginning! From here, you can dive deep into the full range of [configuration options]({{ '/configuration/' | relative_url }}) to create the perfect feed.
diff --git a/index.html b/index.html
deleted file mode 100644
index 8bf05453..00000000
--- a/index.html
+++ /dev/null
@@ -1,25 +0,0 @@
----
-layout: default
-title: html2rss - Home
-nav_order: 0
----
-
-<h1 class="fs-9">html2rss builds RSS feeds from websites which do not have one.</h1>
-<p class="fs-6 fw-300">
-  Start using RSS feeds right away or find out what html2rss has to offer.
-  <br>
-  <a href="./configs/" class="btn btn-primary fs-5 mt-4 mb-4 mb-md-0 mr-2">View the feeds</a>
-  <a href="./components/" class="btn fs-5 mt-4 mb-4 mb-md-0 mr-2">How it works</a>
-</p>
-
-<hr class="my-8">
-
-html2rss is a ecosystem of components with the goals to:
-
-<ol>
-  <li>generate RSS feeds by scraping websites (and JSON APIs).</li>
-  <li>make it easy to build and use a feed config.</li>
-  <li>have multiple decentralized and always up to date instances.</li>
-</ol>
-
-<a href="./components/">Read more</a> about the involved components.
diff --git a/index.md b/index.md
new file mode 100644
index 00000000..ef13414b
--- /dev/null
+++ b/index.md
@@ -0,0 +1,69 @@
+---
+layout: default
+title: Home
+nav_order: 1
+---
+
+# Welcome to html2rss!
+
+**Transform any website into a custom RSS feed.**
+
+Tired of missing updates from websites that don't offer RSS feeds? `html2rss` is a powerful and flexible tool that lets you create your own RSS feeds for almost any website.
+
+Whether you're a developer, a content curator, or just someone who wants to stay on top of the latest news, `html2rss` gives you the power to control your information flow.
+
+---
+
+## How it Works
+
+`html2rss` makes it easy to create custom RSS feeds in just a few steps:
+
+1.  **Install `html2rss`:** Get up and running in minutes with a simple gem installation.
+2.  **Choose your scraper:**
+    - Use the **`auto_source` scraper** to automatically find and extract content from a website.
+    - Use the **`selectors` scraper** for more control, allowing you to specify exactly what content to extract using CSS selectors.
+3.  **Generate your feed:** Run a simple command to generate your custom RSS feed.
+4.  **Stay updated:** Use your favorite RSS reader to subscribe to your new feed and never miss an update.
+
+---
+
+### Key Features
+
+- **Automatic Feed Generation:** The `auto_source` scraper intelligently finds and extracts content from websites, so you can create feeds with minimal effort.
+- **Precise Content Extraction:** Use familiar CSS selectors to target the exact content you want to include in your feed.
+- **JSON Support:** Scrape and handle JSON responses from APIs and other web services.
+- **JavaScript Rendering:** Use a headless browser to render JavaScript-heavy websites and extract content that isn't available in the initial HTML.
+- **Customizable HTTP Headers:** Set custom HTTP headers for your requests, allowing you to access protected content or interact with APIs.
+- **Open Source:** `html2rss` is free to use, modify, and contribute to.
+
+---
+
+### Get Started in Minutes
+
+Ready to create your first custom RSS feed? Our comprehensive documentation will guide you through the process, from installation to advanced configurations.
+
+[**🚀 Get Started Now!**]({{ '/getting-started/' | relative_url }})
+
+---
+
+### Examples & Recipes
+
+Explore our collection of pre-built recipes and examples to see `html2rss` in action and get inspiration for your own feeds.
+
+[**📚 Browse Examples**]({{ '/examples/' | relative_url }})
+
+---
+
+### Join the Community
+
+Have a question, an idea, or a success story to share? Join the `html2rss` community on GitHub!
+
+- **[Discussions](https://github.com/orgs/html2rss/discussions):** Ask questions, share ideas, and connect with other users.
+- **[Issues](https://github.com/html2rss/html2rss/issues):** Report bugs and request new features.
+- **[Contribute](https://github.com/html2rss/html2rss/fork):** Fork the repository and submit your own improvements.
+
+---
+
+### Need Help?
+
+Check out our [Troubleshooting Guide]({{ '/support/troubleshooting/' | relative_url }}) or [Contact Us]({{ '/support/contact/' | relative_url }}) for support.
diff --git a/support/contact.md b/support/contact.md
new file mode 100644
index 00000000..61299582
--- /dev/null
+++ b/support/contact.md
@@ -0,0 +1,36 @@
+---
+layout: default
+title: Contact
+nav_order: 9
+---
+
+# Contact & Support
+
+We're here to help! If you have questions, feedback, or need assistance with `html2rss`, please use the following channels.
+
+---
+
+### 1. GitHub Issues
+
+For bug reports, feature requests, or general technical questions, the best place to get support is by opening an issue on our GitHub repository:
+
+[**➡️ Open an Issue on GitHub**](https://github.com/html2rss/html2rss/issues)
+
+When opening an issue, please provide as much detail as possible, including:
+
+- The `html2rss` version you are using.
+- Your operating system.
+- Your configuration file (if applicable).
+- The target URL you are trying to scrape.
+- Any error messages you receive.
+- Steps to reproduce the issue.
+
+---
+
+### 2. Community Discussions
+
+Join our community discussions on [GitHub Discussions](https://github.com/orgs/html2rss/discussions) to chat with other users and contributors. This is a great place for general questions, sharing tips, and discussing ideas.
+
+---
+
+We look forward to hearing from you!
diff --git a/support/troubleshooting.md b/support/troubleshooting.md
new file mode 100644
index 00000000..8fb72b5f
--- /dev/null
+++ b/support/troubleshooting.md
@@ -0,0 +1,109 @@
+---
+layout: default
+title: Troubleshooting
+nav_order: 6
+---
+
+# Troubleshooting html2rss
+
+Encountering issues while creating your RSS feeds? Don't worry, it happens! This section provides solutions to common problems and tips for debugging your html2rss configurations.
+
+---
+
+## Before You Start: Essential Tools for Troubleshooting
+
+To effectively troubleshoot `html2rss` feeds, you'll primarily use your web browser's developer tools. These tools help you inspect the structure of web pages to find the right selectors.
+
+- **How to open:** Right-click on any element on a webpage and select "Inspect" or "Inspect Element." Look for tabs like "Elements" or "Inspector."
+
+---
+
+### 1. No Items in the Feed / Empty Feed
+
+**Possible Causes:**
+
+- **Incorrect `url`:** Double-check that the `url` in your configuration file is correct and accessible.
+- **Incorrect `items.selector`:** The most common reason. The CSS selector for your items might not be matching any elements on the page.
+- **Website Structure Changed:** Websites frequently update their HTML structure. Your selectors might have become outdated.
+
+**Solutions:**
+
+- **Verify URL:** Open the `url` in your browser to ensure it's correct.
+- **Inspect Element:** Use your browser's "Inspect Element" (or "Developer Tools") feature to examine the HTML structure of the target website. This allows you to see the underlying code of the webpage. Carefully identify the CSS classes or IDs of the elements you want to scrape.
+- **Test Selectors:** In your browser's developer console (usually accessible within the Developer Tools), you can test CSS selectors directly. For example, typing `document.querySelectorAll('.post-item')` and pressing Enter will show you all elements on the current page that match that specific selector. This is a quick way to verify if your selector is correct before putting it into your `html2rss` configuration.
+
+---
+
+### 2. Item Parts (Title, Link, Description) Are Missing or Incorrect
+
+**Possible Causes:**
+
+- **Incorrect `selector` for the part:** Similar to `items.selector`, the selector for `title`, `link`, `description`, etc., might be wrong or outdated. Remember these selectors are relative to the `items.selector` match (i.e., they look for elements _within_ each item found by `items.selector`).
+- **Incorrect `extract` attribute:** You might be trying to `extract: text` (to get the visible text) when you need `extract: href` (to get a link URL), or another attribute like `src` for an image.
+- **Content is dynamically loaded:** Some websites load content using JavaScript _after_ the initial page load. `html2rss` primarily works with the initial HTML content it receives, not content that appears later through JavaScript.
+
+**Solutions:**
+
+- **Inspect Element:** Again, use browser developer tools to find the exact selectors and attributes you need. Pay close attention to the HTML structure around the missing content.
+- **Check `extract` value:** Double-check that you're extracting the correct attribute (e.g., `text`, `href`, `src`).
+- **Dynamic Content:** If the content you're trying to scrape only appears after a delay, or after you scroll down, or after clicking something in your browser, `html2rss` might not see it. This is a limitation for purely static scraping.
+  - **How to check for dynamic content:** Load the page in your browser, then immediately disable JavaScript (often an option in developer tools or browser settings) and refresh the page. If the content disappears, it's likely dynamically loaded.
+  - **Alternatives:** Consider if the website offers an API (Application Programming Interface) or a different URL that provides the content directly in a static format (like JSON or a simpler HTML page).
+
+---
+
+### 3. Date/Time Parsing Issues
+
+**Possible Causes:**
+
+- **Incorrect `time_format`:** The `time_format` in your configuration might not match the actual date string format on the website.
+- **Incorrect `time_zone`:** The time zone might be off, leading to incorrect timestamps.
+
+**Solutions:**
+
+- **Match `time_format`:** Refer to [Ruby's `strptime` documentation](https://ruby-doc.org/core-3.0.0/Time.html#method-c-strptime) to ensure your format string (`%Y-%m-%d`, `%H:%M:%S`, etc.) accurately reflects the date string you're scraping.
+- **Specify `time_zone`:** If the website's dates are in a specific time zone, explicitly set `time_zone` (e.g., `Europe/Berlin`, `America/New_York`).
+
+---
+
+### 4. html2rss Command Not Found
+
+**Possible Causes:**
+
+- **Not in PATH:** The `html2rss` executable might not be in your system's PATH. This means your operating system doesn't know where to find the `html2rss` command when you type it.
+- **Installation Issue:** `html2rss` might not have been installed correctly.
+
+**Solutions:**
+
+- **Re-install:** First, try reinstalling `html2rss` to ensure all components are in place:
+  ```bash
+  gem install html2rss
+  ```
+- **Check Your PATH (Advanced):**
+  - **What is PATH?** The `PATH` is an environment variable that tells your shell where to look for executable programs.
+  - **How to check:**
+    - **macOS/Linux:** Open your terminal and type `echo $PATH`. You'll see a list of directories separated by colons.
+    - **Windows (Command Prompt):** Open Command Prompt and type `echo %PATH%`. You'll see a list of directories separated by semicolons.
+  - **What to look for:** You need to ensure that the directory where Ruby gems install their executables is included in your `PATH`. Common locations include:
+    - `~/.rbenv/shims` (if using rbenv)
+    - `~/.rvm/bin` (if using RVM)
+    - `/usr/local/bin`
+    - A directory specific to your Ruby installation (e.g., `/usr/bin/gem`).
+  - **How to add to PATH (if missing):** This is an advanced step and varies by operating system and shell. You typically add a line to your shell's configuration file (e.g., `.bashrc`, `.zshrc`, `.profile` on macOS/Linux, or system environment variables on Windows) like:
+    ```bash
+    export PATH="/path/to/gem/bin:$PATH"
+    ```
+    After modifying, you'll need to restart your terminal or run `source ~/.bashrc` (or your respective config file). If you're unsure, searching online for "add Ruby gem bin to PATH [your operating system]" can provide detailed instructions.
+
+---
+
+---
+
+### Still Stuck?
+
+If you've tried these solutions and are still facing issues, please don't hesitate to reach out:
+
+- **Open an Issue on GitHub:** Provide your configuration file, the target URL, and a detailed description of the problem.
+- **Check the Community:** Look for similar issues or discussions on the project's GitHub page.
+
+Providing as much detail as possible (your config, the exact URL, error messages, what you've tried) will help us assist you more effectively.

From f77cbd1075e49997a3e2dec8057f754d9a9ed1a2 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 26 Jul 2025 13:48:05 +0200
Subject: [PATCH 02/17] feat(docs): Restructure into Ruby Gem and Web App
 sections

Reorganize the documentation to create a clear distinction between the `html2rss` Ruby Gem and the standalone Web Application. This improves navigation and helps users find content relevant to their specific use case.

- Move all existing gem-related documentation (getting started, configuration, examples) into a new `/ruby-gem` directory.
- Add a new, comprehensive documentation section for the Web Application under `/web-application`.
- Update site-wide navigation, internal links, and page front matter to align with the new structure.
- Update gem dependencies in `Gemfile.lock`.
---
 _config.yml                                   |  3 -
 about.md                                      |  2 +-
 configuration/index.md                        | 24 ------
 examples/custom-http-requests.md              | 14 ----
 examples/handling-dynamic-content.md          | 14 ----
 getting-started/index.md                      | 41 ----------
 index.md                                      | 46 +++---------
 .../configuration}/auto_source.md             |  4 +-
 .../configuration}/channel.md                 |  4 +-
 .../configuration}/headers.md                 |  6 +-
 ruby-gem/configuration/index.md               | 25 +++++++
 .../configuration}/selectors/extractors.md    |  3 +
 .../configuration}/selectors/index.md         |  9 ++-
 .../selectors/post-processors.md              |  3 +
 .../configuration}/strategy.md                |  4 +-
 .../configuration}/stylesheets.md             |  4 +-
 .../examples}/advanced-content-extraction.md  | 10 ++-
 ruby-gem/examples/custom-http-requests.md     | 16 ++++
 .../examples}/dynamic-parameters.md           |  6 +-
 ruby-gem/examples/handling-dynamic-content.md | 16 ++++
 {examples => ruby-gem/examples}/index.md      |  4 +-
 .../examples}/simple-blog-list.md             |  4 +-
 .../examples}/styling-rss-feed.md             |  6 +-
 ruby-gem/getting-started.md                   | 42 +++++++++++
 ruby-gem/index.md                             | 19 +++++
 {getting-started => ruby-gem}/installation.md |  9 ++-
 .../your-first-feed.md                        |  7 +-
 web-application/contributing/index.md         | 15 ++++
 web-application/getting-started/index.md      | 74 +++++++++++++++++++
 web-application/guides/automatic-updates.md   | 14 ++++
 .../guides/creating-custom-feeds.md           | 16 ++++
 web-application/guides/deployment.md          | 32 ++++++++
 web-application/guides/index.md               | 12 +++
 web-application/guides/monitoring.md          | 30 ++++++++
 web-application/index.md                      | 20 +++++
 web-application/reference/configuration.md    | 32 ++++++++
 web-application/reference/included-configs.md | 21 ++++++
 web-application/reference/index.md            | 12 +++
 38 files changed, 463 insertions(+), 160 deletions(-)
 delete mode 100644 configuration/index.md
 delete mode 100644 examples/custom-http-requests.md
 delete mode 100644 examples/handling-dynamic-content.md
 delete mode 100644 getting-started/index.md
 rename {configuration => ruby-gem/configuration}/auto_source.md (96%)
 rename {configuration => ruby-gem/configuration}/channel.md (96%)
 rename {configuration => ruby-gem/configuration}/headers.md (88%)
 create mode 100644 ruby-gem/configuration/index.md
 rename {configuration => ruby-gem/configuration}/selectors/extractors.md (91%)
 rename {configuration => ruby-gem/configuration}/selectors/index.md (92%)
 rename {configuration => ruby-gem/configuration}/selectors/post-processors.md (94%)
 rename {configuration => ruby-gem/configuration}/strategy.md (97%)
 rename {configuration => ruby-gem/configuration}/stylesheets.md (95%)
 rename {examples => ruby-gem/examples}/advanced-content-extraction.md (54%)
 create mode 100644 ruby-gem/examples/custom-http-requests.md
 rename {examples => ruby-gem/examples}/dynamic-parameters.md (89%)
 create mode 100644 ruby-gem/examples/handling-dynamic-content.md
 rename {examples => ruby-gem/examples}/index.md (94%)
 rename {examples => ruby-gem/examples}/simple-blog-list.md (95%)
 rename {examples => ruby-gem/examples}/styling-rss-feed.md (50%)
 create mode 100644 ruby-gem/getting-started.md
 create mode 100644 ruby-gem/index.md
 rename {getting-started => ruby-gem}/installation.md (92%)
 rename {getting-started => ruby-gem}/your-first-feed.md (91%)
 create mode 100644 web-application/contributing/index.md
 create mode 100644 web-application/getting-started/index.md
 create mode 100644 web-application/guides/automatic-updates.md
 create mode 100644 web-application/guides/creating-custom-feeds.md
 create mode 100644 web-application/guides/deployment.md
 create mode 100644 web-application/guides/index.md
 create mode 100644 web-application/guides/monitoring.md
 create mode 100644 web-application/index.md
 create mode 100644 web-application/reference/configuration.md
 create mode 100644 web-application/reference/included-configs.md
 create mode 100644 web-application/reference/index.md

diff --git a/_config.yml b/_config.yml
index cca1453a..201a1553 100644
--- a/_config.yml
+++ b/_config.yml
@@ -24,9 +24,6 @@ aux_links:
   "GitHub":
     - "https://github.com/html2rss"
 
-header_pages:
-  - configs/index.html
-  - contributing.md
 
 # Footer "Edit this page on GitHub" link text
 gh_edit_link: true # show or hide edit this page link
diff --git a/about.md b/about.md
index 8f509a46..c0ca94b8 100644
--- a/about.md
+++ b/about.md
@@ -41,4 +41,4 @@ The `html2rss` project is more than just a single tool. It's a collection of too
 
 `html2rss` is maintained by a dedicated group of volunteers and contributors from around the world. We are passionate about open source and committed to continuously improving the project.
 
-Want to join us? Check out our [Contributing Guide]({{ '/contributing/' | relative_url }})!
+Want to join us? Check out our [Contributing Guide]({{ '/contributing' | relative_url }})!
diff --git a/configuration/index.md b/configuration/index.md
deleted file mode 100644
index 4b2fb072..00000000
--- a/configuration/index.md
+++ /dev/null
@@ -1,24 +0,0 @@
----
-layout: default
-title: Configuration
-nav_order: 4
-has_children: true
----
-
-# Configuration
-
-While the `html2rss auto` command is a great starting point, you'll often need to create a YAML configuration file to get the perfect RSS feed. A configuration file gives you fine-grained control over every aspect of the feed generation process.
-
-This section provides a comprehensive guide to all the configuration options available in `html2rss`.
-
-## Configuration Topics
-
-- [**Auto Source**]({{ '/configuration/auto_source/' | relative_url }}): The easiest way to create a feed, with minimal configuration.
-- [**Channel**]({{ '/configuration/channel/' | relative_url }}): Customize the metadata of your RSS feed.
-- [**Selectors**]({{ '/configuration/selectors/' | relative_url }}): Use CSS selectors to extract content with precision.
-- [**Extractors**]({{ '/configuration/selectors/extractors/' | relative_url }}): Specify how to extract information from HTML elements.
-- [**Post Processors**]({{ '/configuration/selectors/post-processors/' | relative_url }}): Manipulate the extracted data to get it just right.
-- [**Strategy**]({{ '/configuration/strategy/' | relative_url }}): Define how html2rss fetches website content, including JavaScript rendering options.
-- [**Headers**]({{ '/configuration/headers/' | relative_url }}): Set custom HTTP headers for requests, useful for APIs and authorization.
-- [**Stylesheets**]({{ '/configuration/stylesheets/' | relative_url }}): Add CSS or XSLT stylesheets to style your RSS feed in browsers.
-- [**Advanced Topics**]({{ '/configuration/advanced-topics/' | relative_url }}): Learn about advanced features like strategies, custom headers, and dynamic parameters.
diff --git a/examples/custom-http-requests.md b/examples/custom-http-requests.md
deleted file mode 100644
index 41c66139..00000000
--- a/examples/custom-http-requests.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-layout: default
-title: Customizing HTTP Requests
-nav_order: 8
-parent: Examples
----
-
-# Customizing HTTP Requests
-
-You might need to send custom HTTP headers (e.g., `User-Agent`, `Authorization`) to access certain content or interact with APIs.
-
-## Solution
-
-Configure [custom HTTP headers](/configuration/headers) in your feed configuration.
diff --git a/examples/handling-dynamic-content.md b/examples/handling-dynamic-content.md
deleted file mode 100644
index fe3fd4d3..00000000
--- a/examples/handling-dynamic-content.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-layout: default
-title: Handling Dynamic Content and JavaScript
-nav_order: 7
-parent: Examples
----
-
-# Handling Dynamic Content and JavaScript
-
-Some websites load their content dynamically using JavaScript. The default `html2rss` strategy might not see this content.
-
-## Solution
-
-Use the [`browserless` strategy](/configuration/strategy) to render JavaScript-heavy websites with a headless browser.
diff --git a/getting-started/index.md b/getting-started/index.md
deleted file mode 100644
index 1ad6c58e..00000000
--- a/getting-started/index.md
+++ /dev/null
@@ -1,41 +0,0 @@
----
-layout: default
-title: Getting Started
-nav_order: 3
-has_children: true
----
-
-# Getting Started with html2rss
-
-Welcome to the `html2rss` quick start guide! This section will walk you through the essential steps to get `html2rss` up and running and create your very first custom RSS feed.
-
-We've designed this guide to be as straightforward as possible, whether you're a seasoned developer or new to web scraping.
-
----
-
-## Where to Start
-
-We recommend starting with the installation guide to set up `html2rss` on your system. Once installed, proceed to our step-by-step guide to creating your first feed. It covers everything from the simplest "no-config" method to creating a custom feed with CSS selectors.
-
-[**⚙️ Start with Installation**]({{ '/getting-started/installation/' | relative_url }})
-
-[**🚀 Then, move to "Your First Feed" Guide**]({{ '/getting-started/your-first-feed/' | relative_url }})
-
----
-
-## Automatic Generation (auto_source)
-
-For those looking for the quickest way to get started, `html2rss` offers an automatic method (`auto_source`) that intelligently scrapes a page to find content. This approach requires minimal setup and is perfect for a rapid start.
-
-[**⚡️ Learn about the "Automatic Generation" Method**]({{ '/getting-started/your-first-feed/#step-1-the-no-config-method-auto' | relative_url }})
-
----
-
-## Other Topics
-
-- [**Handling Dynamic Content and JavaScript**]({{ '/examples/handling-dynamic-content/' | relative_url }}): Learn how to handle JavaScript-heavy websites.
-- [**Customizing HTTP Requests**]({{ '/examples/custom-http-requests/' | relative_url }}): How to send custom HTTP headers.
-- [**Dynamic Parameters in URLs and Headers**]({{ '/examples/dynamic-parameters/' | relative_url }}): Use dynamic parameters in URLs and headers.
-- [**Advanced Content Extraction with Selectors**]({{ '/examples/advanced-content-extraction/' | relative_url }}): Precise content extraction techniques.
-- [**Styling Your RSS Feed**]({{ '/examples/styling-rss-feed/' | relative_url }}): Add stylesheets to your RSS feed.
-- [**Debugging Your Configuration**]({{ '/examples/debugging-configuration/' | relative_url }}): Debug your feed configuration effectively.
diff --git a/index.md b/index.md
index ef13414b..d2a2a83b 100644
--- a/index.md
+++ b/index.md
@@ -4,56 +4,34 @@ title: Home
 nav_order: 1
 ---
 
-# Welcome to html2rss!
-
-**Transform any website into a custom RSS feed.**
+# Create RSS Feeds for Any Website
 
 Tired of missing updates from websites that don't offer RSS feeds? `html2rss` is a powerful and flexible tool that lets you create your own RSS feeds for almost any website.
 
-Whether you're a developer, a content curator, or just someone who wants to stay on top of the latest news, `html2rss` gives you the power to control your information flow.
+[**🚀 Get Started with the Web App!**]({{ '/web-application/getting-started' | relative_url }})
 
 ---
 
-## How it Works
+## The html2rss Ecosystem
 
-`html2rss` makes it easy to create custom RSS feeds in just a few steps:
+`html2rss` is a suite of tools designed to help you create and manage RSS feeds.
 
-1.  **Install `html2rss`:** Get up and running in minutes with a simple gem installation.
-2.  **Choose your scraper:**
-    - Use the **`auto_source` scraper** to automatically find and extract content from a website.
-    - Use the **`selectors` scraper** for more control, allowing you to specify exactly what content to extract using CSS selectors.
-3.  **Generate your feed:** Run a simple command to generate your custom RSS feed.
-4.  **Stay updated:** Use your favorite RSS reader to subscribe to your new feed and never miss an update.
+*   **[html2rss-web]({{ '/web-application' | relative_url }}):** A user-friendly web application that makes it easy to create, manage, and share RSS feeds. This is the recommended starting point for most users.
+*   **[html2rss (Ruby Gem)]({{ '/ruby-gem' | relative_url }}):** The core library that powers the web application. It provides a powerful and flexible command-line interface for creating custom RSS feeds.
+*   **[html2rss-configs](https://github.com/html2rss/html2rss-configs):** A community-driven repository of pre-built feed configurations for popular websites.
 
 ---
 
-### Key Features
+## Key Features
 
+- **User-Friendly Web Interface:** The `html2rss-web` application provides a simple and intuitive interface for managing your feeds.
 - **Automatic Feed Generation:** The `auto_source` scraper intelligently finds and extracts content from websites, so you can create feeds with minimal effort.
 - **Precise Content Extraction:** Use familiar CSS selectors to target the exact content you want to include in your feed.
-- **JSON Support:** Scrape and handle JSON responses from APIs and other web services.
 - **JavaScript Rendering:** Use a headless browser to render JavaScript-heavy websites and extract content that isn't available in the initial HTML.
-- **Customizable HTTP Headers:** Set custom HTTP headers for your requests, allowing you to access protected content or interact with APIs.
 - **Open Source:** `html2rss` is free to use, modify, and contribute to.
 
 ---
 
-### Get Started in Minutes
-
-Ready to create your first custom RSS feed? Our comprehensive documentation will guide you through the process, from installation to advanced configurations.
-
-[**🚀 Get Started Now!**]({{ '/getting-started/' | relative_url }})
-
----
-
-### Examples & Recipes
-
-Explore our collection of pre-built recipes and examples to see `html2rss` in action and get inspiration for your own feeds.
-
-[**📚 Browse Examples**]({{ '/examples/' | relative_url }})
-
----
-
 ### Join the Community
 
 Have a question, an idea, or a success story to share? Join the `html2rss` community on GitHub!
@@ -61,9 +39,3 @@ Have a question, an idea, or a success story to share? Join the `html2rss` commu
 - **[Discussions](https://github.com/orgs/html2rss/discussions):** Ask questions, share ideas, and connect with other users.
 - **[Issues](https://github.com/html2rss/html2rss/issues):** Report bugs and request new features.
 - **[Contribute](https://github.com/html2rss/html2rss/fork):** Fork the repository and submit your own improvements.
-
----
-
-### Need Help?
-
-Check out our [Troubleshooting Guide]({{ '/support/troubleshooting/' | relative_url }}) or [Contact Us]({{ '/support/contact/' | relative_url }}) for support.
diff --git a/configuration/auto_source.md b/ruby-gem/configuration/auto_source.md
similarity index 96%
rename from configuration/auto_source.md
rename to ruby-gem/configuration/auto_source.md
index b0515f3d..b6440448 100644
--- a/configuration/auto_source.md
+++ b/ruby-gem/configuration/auto_source.md
@@ -1,8 +1,10 @@
 ---
 layout: default
 title: Auto Source
-nav_order: 4
+nav_order: 1
 parent: Configuration
+grand_parent: Ruby Gem
+permalink: /ruby-gem/configuration/auto_source
 ---
 
 # `auto_source`
diff --git a/configuration/channel.md b/ruby-gem/configuration/channel.md
similarity index 96%
rename from configuration/channel.md
rename to ruby-gem/configuration/channel.md
index 47de9e1f..25122c50 100644
--- a/configuration/channel.md
+++ b/ruby-gem/configuration/channel.md
@@ -1,8 +1,10 @@
 ---
 layout: default
 title: Channel
-nav_order: 1
+nav_order: 2
 parent: Configuration
+grand_parent: Ruby Gem
+permalink: /ruby-gem/configuration/channel
 ---
 
 # `channel`
diff --git a/configuration/headers.md b/ruby-gem/configuration/headers.md
similarity index 88%
rename from configuration/headers.md
rename to ruby-gem/configuration/headers.md
index 8b1720ac..f086717c 100644
--- a/configuration/headers.md
+++ b/ruby-gem/configuration/headers.md
@@ -1,8 +1,10 @@
 ---
 layout: default
 title: Headers
-nav_order: 1
+nav_order: 3
 parent: Configuration
+grand_parent: Ruby Gem
+permalink: /ruby-gem/configuration/headers
 ---
 
 # `headers`
@@ -17,7 +19,7 @@ headers:
 
 You can also set headers for APIs that require authorization or custom headers.
 
-Dynamic parameters can be used in headers to pass values at runtime. See [Advanced Topics](/configuration/advanced-topics/) for more details.
+Dynamic parameters can be used in headers to pass values at runtime. See [Dynamic Parameters]({{ '/ruby-gem/examples/dynamic-parameters' | relative_url }}) for more details.
 
 ## Example Configuration
 
diff --git a/ruby-gem/configuration/index.md b/ruby-gem/configuration/index.md
new file mode 100644
index 00000000..c16b66c0
--- /dev/null
+++ b/ruby-gem/configuration/index.md
@@ -0,0 +1,25 @@
+---
+layout: default
+title: Configuration
+nav_order: 4
+parent: Ruby Gem
+has_children: true
+permalink: /ruby-gem/configuration
+---
+
+# Configuration
+
+While the `html2rss auto` command is a great starting point, you'll often need to create a YAML configuration file to get the perfect RSS feed. A configuration file gives you fine-grained control over every aspect of the feed generation process.
+
+This section provides a comprehensive guide to all the configuration options available in `html2rss`.
+
+## Configuration Topics
+
+- [**Auto Source**]({{ '/ruby-gem/configuration/auto_source' | relative_url }}): The easiest way to create a feed, with minimal configuration.
+- [**Channel**]({{ '/ruby-gem/configuration/channel' | relative_url }}): Customize the metadata of your RSS feed.
+- [**Selectors**]({{ '/ruby-gem/configuration/selectors' | relative_url }}): Use CSS selectors to extract content with precision.
+- [**Extractors**]({{ '/ruby-gem/configuration/selectors/extractors' | relative_url }}): Specify how to extract information from HTML elements.
+- [**Post Processors**]({{ '/ruby-gem/configuration/selectors/post-processors' | relative_url }}): Manipulate the extracted data to get it just right.
+- [**Strategy**]({{ '/ruby-gem/configuration/strategy' | relative_url }}): Define how html2rss fetches website content, including JavaScript rendering options.
+- [**Headers**]({{ '/ruby-gem/configuration/headers' | relative_url }}): Set custom HTTP headers for requests, useful for APIs and authorization.
+- [**Stylesheets**]({{ '/ruby-gem/configuration/stylesheets' | relative_url }}): Add CSS or XSLT stylesheets to style your RSS feed in browsers.
diff --git a/configuration/selectors/extractors.md b/ruby-gem/configuration/selectors/extractors.md
similarity index 91%
rename from configuration/selectors/extractors.md
rename to ruby-gem/configuration/selectors/extractors.md
index 27c10622..313c5300 100644
--- a/configuration/selectors/extractors.md
+++ b/ruby-gem/configuration/selectors/extractors.md
@@ -2,6 +2,9 @@
 layout: default
 title: Extractors
 parent: Selectors
+grand_parent: Configuration
+nav_order: 1
+permalink: /ruby-gem/configuration/selectors/extractors
 ---
 
 # Extractors
diff --git a/configuration/selectors/index.md b/ruby-gem/configuration/selectors/index.md
similarity index 92%
rename from configuration/selectors/index.md
rename to ruby-gem/configuration/selectors/index.md
index 6dd01735..da7c4dcb 100644
--- a/configuration/selectors/index.md
+++ b/ruby-gem/configuration/selectors/index.md
@@ -1,8 +1,11 @@
 ---
 layout: default
 title: Selectors
-nav_order: 5
+nav_order: 6
 parent: Configuration
+grand_parent: Ruby Gem
+has_children: true
+permalink: /ruby-gem/configuration/selectors
 ---
 
 # `selectors`
@@ -65,8 +68,8 @@ Each selector can have the following attributes:
 | Name           | Value                                                                                                   |
 | :------------- | :------------------------------------------------------------------------------------------------------ |
 | `selector`     | The CSS selector to select the element with the information.                                            |
-| `extractor`    | The name of the extractor to use. See [Extractors](/configuration/selectors/extractors/).               |
-| `post_process` | An array of post processors to apply. See [Post Processors](/configuration/selectors/post-processors/). |
+| `extractor`    | The name of the extractor to use. See [Extractors]({{ '/ruby-gem/configuration/selectors/extractors' | relative_url }}).               |
+| `post_process` | An array of post processors to apply. See [Post Processors]({{ '/ruby-gem/configuration/selectors/post-processors' | relative_url }}). |
 
 ---
 
diff --git a/configuration/selectors/post-processors.md b/ruby-gem/configuration/selectors/post-processors.md
similarity index 94%
rename from configuration/selectors/post-processors.md
rename to ruby-gem/configuration/selectors/post-processors.md
index fabf8b54..4faab9a1 100644
--- a/configuration/selectors/post-processors.md
+++ b/ruby-gem/configuration/selectors/post-processors.md
@@ -2,6 +2,9 @@
 layout: default
 title: Post Processors
 parent: Selectors
+grand_parent: Configuration
+nav_order: 2
+permalink: /ruby-gem/configuration/selectors/post-processors
 ---
 
 # Post Processors
diff --git a/configuration/strategy.md b/ruby-gem/configuration/strategy.md
similarity index 97%
rename from configuration/strategy.md
rename to ruby-gem/configuration/strategy.md
index 6e01896f..7e9d549f 100644
--- a/configuration/strategy.md
+++ b/ruby-gem/configuration/strategy.md
@@ -1,8 +1,10 @@
 ---
 layout: default
 title: Strategy
-nav_order: 2
+nav_order: 4
 parent: Configuration
+grand_parent: Ruby Gem
+permalink: /ruby-gem/configuration/strategy
 ---
 
 # `strategy`
diff --git a/configuration/stylesheets.md b/ruby-gem/configuration/stylesheets.md
similarity index 95%
rename from configuration/stylesheets.md
rename to ruby-gem/configuration/stylesheets.md
index 747fef7d..1d35efc7 100644
--- a/configuration/stylesheets.md
+++ b/ruby-gem/configuration/stylesheets.md
@@ -1,8 +1,10 @@
 ---
 layout: default
 title: Stylesheets
-nav_order: 3
+nav_order: 5
 parent: Configuration
+grand_parent: Ruby Gem
+permalink: /ruby-gem/configuration/stylesheets
 ---
 
 # `stylesheets`
diff --git a/examples/advanced-content-extraction.md b/ruby-gem/examples/advanced-content-extraction.md
similarity index 54%
rename from examples/advanced-content-extraction.md
rename to ruby-gem/examples/advanced-content-extraction.md
index 16478124..2ae23990 100644
--- a/examples/advanced-content-extraction.md
+++ b/ruby-gem/examples/advanced-content-extraction.md
@@ -1,8 +1,10 @@
 ---
 layout: default
-title: Advanced Content Extraction with Selectors
-nav_order: 10
+title: Advanced Content Extraction
+nav_order: 1
 parent: Examples
+grand_parent: Ruby Gem
+permalink: /ruby-gem/examples/advanced-content-extraction
 ---
 
 # Advanced Content Extraction with Selectors
@@ -11,8 +13,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](/configuration/selectors/extractors/).
+Learn how to extract specific attributes (like `src` for images) or static values. See [Extractors]({{ '/ruby-gem/configuration/selectors/extractors' | relative_url }}).
 
 ## Post Processors
 
-Manipulate extracted text, sanitize HTML, convert Markdown, or apply custom logic. See [Post Processors](/configuration/selectors/post-processors/).
+Manipulate extracted text, sanitize HTML, convert Markdown, or apply custom logic. See [Post Processors]({{ '/ruby-gem/configuration/selectors/post-processors' | relative_url }}).
diff --git a/ruby-gem/examples/custom-http-requests.md b/ruby-gem/examples/custom-http-requests.md
new file mode 100644
index 00000000..cd8506f5
--- /dev/null
+++ b/ruby-gem/examples/custom-http-requests.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: Custom HTTP Requests
+nav_order: 2
+parent: Examples
+grand_parent: Ruby Gem
+permalink: /ruby-gem/examples/custom-http-requests
+---
+
+# Customizing HTTP Requests
+
+You might need to send custom HTTP headers (e.g., `User-Agent`, `Authorization`) to access certain content or interact with APIs.
+
+## Solution
+
+Configure [custom HTTP headers]({{ '/ruby-gem/configuration/headers' | relative_url }}) in your feed configuration.
diff --git a/examples/dynamic-parameters.md b/ruby-gem/examples/dynamic-parameters.md
similarity index 89%
rename from examples/dynamic-parameters.md
rename to ruby-gem/examples/dynamic-parameters.md
index 5256c17e..801d14e8 100644
--- a/examples/dynamic-parameters.md
+++ b/ruby-gem/examples/dynamic-parameters.md
@@ -1,8 +1,10 @@
 ---
 layout: default
-title: Dynamic Parameters in URLs and Headers
-nav_order: 9
+title: Dynamic Parameters
+nav_order: 3
 parent: Examples
+grand_parent: Ruby Gem
+permalink: /ruby-gem/examples/dynamic-parameters
 ---
 
 # Dynamic Parameters in URLs and Headers
diff --git a/ruby-gem/examples/handling-dynamic-content.md b/ruby-gem/examples/handling-dynamic-content.md
new file mode 100644
index 00000000..69cece6f
--- /dev/null
+++ b/ruby-gem/examples/handling-dynamic-content.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: Handling Dynamic Content
+nav_order: 4
+parent: Examples
+grand_parent: Ruby Gem
+permalink: /ruby-gem/examples/handling-dynamic-content
+---
+
+# Handling Dynamic Content and JavaScript
+
+Some websites load their content dynamically using JavaScript. The default `html2rss` strategy might not see this content.
+
+## Solution
+
+Use the [`browserless` strategy]({{ '/ruby-gem/configuration/strategy' | relative_url }}) to render JavaScript-heavy websites with a headless browser.
diff --git a/examples/index.md b/ruby-gem/examples/index.md
similarity index 94%
rename from examples/index.md
rename to ruby-gem/examples/index.md
index 909ff2f3..874eea65 100644
--- a/examples/index.md
+++ b/ruby-gem/examples/index.md
@@ -1,8 +1,10 @@
 ---
 layout: default
 title: Examples
-nav_order: 6
+nav_order: 5
+parent: Ruby Gem
 has_children: true
+permalink: /ruby-gem/examples
 ---
 
 # Examples: Practical `html2rss` Configurations
diff --git a/examples/simple-blog-list.md b/ruby-gem/examples/simple-blog-list.md
similarity index 95%
rename from examples/simple-blog-list.md
rename to ruby-gem/examples/simple-blog-list.md
index 2126a7d6..22c16451 100644
--- a/examples/simple-blog-list.md
+++ b/ruby-gem/examples/simple-blog-list.md
@@ -1,8 +1,10 @@
 ---
 layout: default
 title: Simple Blog List
+nav_order: 5
 parent: Examples
-nav_order: 1
+grand_parent: Ruby Gem
+permalink: /ruby-gem/examples/simple-blog-list
 ---
 
 # Example: Scraping a Simple Blog List
diff --git a/examples/styling-rss-feed.md b/ruby-gem/examples/styling-rss-feed.md
similarity index 50%
rename from examples/styling-rss-feed.md
rename to ruby-gem/examples/styling-rss-feed.md
index 0700eeff..ded55e9f 100644
--- a/examples/styling-rss-feed.md
+++ b/ruby-gem/examples/styling-rss-feed.md
@@ -1,8 +1,10 @@
 ---
 layout: default
 title: Styling Your RSS Feed
-nav_order: 11
+nav_order: 6
 parent: Examples
+grand_parent: Ruby Gem
+permalink: /ruby-gem/examples/styling-rss-feed
 ---
 
 # Styling Your RSS Feed
@@ -11,4 +13,4 @@ You can make your RSS feed look good in a web browser by attaching stylesheets.
 
 ## Solution
 
-Add [stylesheets](/configuration/stylesheets) to your feed configuration.
+Add [stylesheets]({{ '/ruby-gem/configuration/stylesheets' | relative_url }}) to your feed configuration.
diff --git a/ruby-gem/getting-started.md b/ruby-gem/getting-started.md
new file mode 100644
index 00000000..f6fa16bf
--- /dev/null
+++ b/ruby-gem/getting-started.md
@@ -0,0 +1,42 @@
+---
+layout: default
+title: Getting Started
+nav_order: 1
+parent: Ruby Gem
+permalink: /ruby-gem/getting-started
+---
+
+# Getting Started with the html2rss Gem
+
+Welcome to the `html2rss` gem quick start guide! This section will walk you through the essential steps to get `html2rss` up and running and create your very first custom RSS feed from the command line.
+
+We've designed this guide to be as straightforward as possible, whether you're a seasoned developer or new to web scraping.
+
+---
+
+## Where to Start
+
+We recommend starting with the installation guide to set up `html2rss` on your system. Once installed, proceed to our step-by-step guide to creating your first feed. It covers everything from the simplest "no-config" method to creating a custom feed with CSS selectors.
+
+[**⚙️ Start with Installation**]({{ '/ruby-gem/installation' | relative_url }})
+
+[**🚀 Then, move to the "Your First Feed" Guide**]({{ '/ruby-gem/your-first-feed' | relative_url }})
+
+---
+
+## Automatic Generation (auto_source)
+
+For those looking for the quickest way to get started, `html2rss` offers an automatic method (`auto_source`) that intelligently scrapes a page to find content. This approach requires minimal setup and is perfect for a rapid start.
+
+[**⚡️ Learn about the "Automatic Generation" Method**]({{ '/ruby-gem/your-first-feed/#step-1-the-no-config-method-auto' | relative_url }})
+
+---
+
+## Other Topics
+
+- [**Handling Dynamic Content and JavaScript**]({{ '/ruby-gem/examples/handling-dynamic-content' | relative_url }}): Learn how to handle JavaScript-heavy websites.
+- [**Customizing HTTP Requests**]({{ '/ruby-gem/examples/custom-http-requests' | relative_url }}): How to send custom HTTP headers.
+- [**Dynamic Parameters in URLs and Headers**]({{ '/ruby-gem/examples/dynamic-parameters' | relative_url }}): Use dynamic parameters in URLs and headers.
+- [**Advanced Content Extraction with Selectors**]({{ '/ruby-gem/examples/advanced-content-extraction' | relative_url }}): Precise content extraction techniques.
+- [**Styling Your RSS Feed**]({{ '/ruby-gem/examples/styling-rss-feed' | relative_url }}): Add stylesheets to your RSS feed.
+- [**Debugging Your Configuration**]({{ '/support/troubleshooting' | relative_url }}): Debug your feed configuration effectively.
diff --git a/ruby-gem/index.md b/ruby-gem/index.md
new file mode 100644
index 00000000..f951d6a9
--- /dev/null
+++ b/ruby-gem/index.md
@@ -0,0 +1,19 @@
+---
+layout: default
+title: Ruby Gem
+nav_order: 3
+has_children: true
+permalink: /ruby-gem
+---
+
+# For Developers: The html2rss Ruby Gem
+
+This section provides detailed documentation for the `html2rss` Ruby gem. The gem is the core library that powers the `html2rss-web` application.
+
+If you are looking for the easiest way to get started with `html2rss`, we recommend using the [web application]({{ '/web-application' | relative_url }}).
+
+This documentation is for developers who want to:
+
+*   Use the `html2rss` gem directly from the command line.
+*   Integrate the `html2rss` gem into their own Ruby applications.
+*   Contribute to the development of `html2rss`.
diff --git a/getting-started/installation.md b/ruby-gem/installation.md
similarity index 92%
rename from getting-started/installation.md
rename to ruby-gem/installation.md
index defc5c2e..6bed934a 100644
--- a/getting-started/installation.md
+++ b/ruby-gem/installation.md
@@ -1,8 +1,9 @@
 ---
 layout: default
 title: Installation
-parent: Getting Started
-nav_order: 1
+nav_order: 2
+parent: Ruby Gem
+permalink: /ruby-gem/installation
 ---
 
 # Installation
@@ -63,10 +64,10 @@ To ensure html2rss is installed correctly, open your terminal and run:
 html2rss --version
 ```
 
-You should see the installed version number. If you encounter any issues, please refer to the [Troubleshooting Guide]({{ "/support/troubleshooting/" | relative_url }}).
+You should see the installed version number. If you encounter any issues, please refer to the [Troubleshooting Guide]({{ "/support/troubleshooting" | relative_url }}).
 
 ---
 
 ### Next Steps
 
-Now that html2rss is installed, let's create your [first RSS feed]({{ "/getting-started/your-first-feed/" | relative_url }})!
+Now that html2rss is installed, let's create your [first RSS feed]({{ '/ruby-gem/your-first-feed' | relative_url }})!
diff --git a/getting-started/your-first-feed.md b/ruby-gem/your-first-feed.md
similarity index 91%
rename from getting-started/your-first-feed.md
rename to ruby-gem/your-first-feed.md
index 28e65ba5..0c05ce36 100644
--- a/getting-started/your-first-feed.md
+++ b/ruby-gem/your-first-feed.md
@@ -1,8 +1,9 @@
 ---
 layout: default
 title: Your First Feed
-nav_order: 1
-parent: Getting Started
+nav_order: 3
+parent: Ruby Gem
+permalink: /ruby-gem/your-first-feed
 ---
 
 # Your First Feed: A Step-by-Step Guide
@@ -62,4 +63,4 @@ This configuration tells `html2rss`:
 - The `title` of each item is the text of the `<a>` tag.
 - The `url` of each item is the `href` attribute of the `<a>` tag.
 
-This is just the beginning! From here, you can dive deep into the full range of [configuration options]({{ '/configuration/' | relative_url }}) to create the perfect feed.
+This is just the beginning! From here, you can dive deep into the full range of [configuration options]({{ '/ruby-gem/configuration' | relative_url }}) to create the perfect feed.
diff --git a/web-application/contributing/index.md b/web-application/contributing/index.md
new file mode 100644
index 00000000..391291e8
--- /dev/null
+++ b/web-application/contributing/index.md
@@ -0,0 +1,15 @@
+---
+layout: default
+title: Contributing
+nav_order: 4
+permalink: /web-application/contributing
+parent: Web Application
+---
+
+# Contributing
+
+Contributions are welcome!
+
+Open a pull request with your changes,
+open an issue, or
+[join discussions on html2rss](https://github.com/orgs/html2rss/discussions).
diff --git a/web-application/getting-started/index.md b/web-application/getting-started/index.md
new file mode 100644
index 00000000..80f5bd31
--- /dev/null
+++ b/web-application/getting-started/index.md
@@ -0,0 +1,74 @@
+---
+layout: default
+title: Getting Started
+nav_order: 1
+permalink: /web-application/getting-started
+parent: Web Application
+---
+
+# Getting Started with html2rss-web
+
+In this guide, you'll launch the `html2rss-web` application on your local machine. By the end, you'll have a running instance and your first live RSS feed.
+
+## Get Started in 5 Minutes
+
+The easiest way to get started is with Docker.
+
+### 1. Create Your `docker-compose.yml`
+
+Create a file named `docker-compose.yml` and paste in the following:
+
+```yaml
+services:
+  html2rss-web:
+    image: gilcreator/html2rss-web
+    ports:
+      - "3000:3000"
+    volumes:
+      - type: bind
+        source: ./feeds.yml
+        target: /app/config/feeds.yml
+        read_only: true
+    environment:
+      RACK_ENV: production
+      HEALTH_CHECK_USERNAME: health
+      HEALTH_CHECK_PASSWORD: please-set-YOUR-OWN-veeeeeery-l0ng-aNd-h4rd-to-gue55-Passw0rd!
+      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:3001
+      BROWSERLESS_IO_API_TOKEN: 6R0W53R135510
+
+  watchtower:
+    image: containrrr/watchtower
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - "~/.docker/config.json:/config.json"
+    command: --cleanup --interval 7200
+
+  browserless:
+    image: "ghcr.io/browserless/chromium"
+    ports:
+      - "3001:3001"
+    environment:
+      PORT: 3001
+      CONCURRENT: 10
+      TOKEN: 6R0W53R135510
+```
+
+### 2. Create an Empty `feeds.yml`
+
+The application needs a place to store your custom feed configurations.
+
+```bash
+touch feeds.yml
+```
+
+### 3. Launch the Application
+
+```bash
+docker-compose up
+```
+
+Congratulations! The `html2rss-web` application is now running. Open your browser to `http://localhost:3000` to see it in action.
+
+### Next Up
+
+Now that you have the application running, let's [create your first custom feed]({{ '/web-application/guides/creating-custom-feeds' | relative_url }}).
diff --git a/web-application/guides/automatic-updates.md b/web-application/guides/automatic-updates.md
new file mode 100644
index 00000000..4b97d139
--- /dev/null
+++ b/web-application/guides/automatic-updates.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: Automatic Updates
+nav_order: 3
+permalink: /web-application/guides/automatic-updates
+parent: Guides
+grand_parent: Web Application
+---
+
+# Automatic Updates with Watchtower
+
+The [watchtower](https://containrrr.dev/watchtower/) service automatically pulls running Docker images and checks for updates. If an update is available, it will automatically start the updated image with the same configuration as the running one. Please read its manual.
+
+The `docker-compose.yml` in the [Getting Started guide]({{ '/web-application/getting-started' | relative_url }}) contains a service description for watchtower.
diff --git a/web-application/guides/creating-custom-feeds.md b/web-application/guides/creating-custom-feeds.md
new file mode 100644
index 00000000..586eccde
--- /dev/null
+++ b/web-application/guides/creating-custom-feeds.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: Creating Custom Feeds
+nav_order: 1
+permalink: /web-application/guides/creating-custom-feeds
+parent: Guides
+grand_parent: Web Application
+---
+
+# Creating Your First Custom Feed
+
+To build your own RSS feed, you need to create a _feed config_. That _feed config_ goes into the file `feeds.yml`.
+
+Check out the [`example` feed config](https://github.com/html2rss/html2rss-web/blob/master/config/feeds.yml#L9).
+
+Please refer to [html2rss' README for a description of the feed config and its options](https://github.com/html2rss/html2rss#the-feed-config-and-its-options). html2rss-web is just a small web application that builds on html2rss.
diff --git a/web-application/guides/deployment.md b/web-application/guides/deployment.md
new file mode 100644
index 00000000..cc19fa66
--- /dev/null
+++ b/web-application/guides/deployment.md
@@ -0,0 +1,32 @@
+---
+layout: default
+title: Deploying to Production
+nav_order: 2
+permalink: /web-application/guides/deployment
+parent: Guides
+grand_parent: Web Application
+---
+
+# Deploying to Production
+
+This app is published on Docker Hub and therefore easy to use with Docker.
+The `docker-compose.yml` from the [Getting Started guide]({{ '/web-application/getting-started' | relative_url }}) is a good starting point.
+
+If you're going to host a public instance, _please, please, please_:
+
+- Put the application behind a reverse proxy.
+- Allow outside connections only via HTTPS.
+- Have an auto-update strategy (e.g., watchtower).
+- Monitor your `/health_check.txt` endpoint.
+- [Let the world know and add your instance to the wiki](https://github.com/html2rss/html2rss-web/wiki/Instances) -- thank you!
+
+## Versioning and Releases
+
+This web application is distributed in a [rolling release](https://en.wikipedia.org/wiki/Rolling_release) fashion from the `master` branch.
+
+For the latest commit passing GitHub CI/CD on the master branch, an updated Docker image will be pushed to [Docker Hub: `gilcreator/html2rss-web`](https://hub.docker.com/r/gilcreator/html2rss-web).
+The [SBOM](https://en.wikipedia.org/wiki/Software_supply_chain) is embedded in the Docker image.
+
+GitHub's @dependabot is enabled for dependency updates and they are automatically merged to the `master` branch when the CI gives the green light.
+
+If you use Docker, you should update to the latest image automatically by [setting up _watchtower_ as described]({{ '/web-application/guides/automatic-updates' | relative_url }}).
diff --git a/web-application/guides/index.md b/web-application/guides/index.md
new file mode 100644
index 00000000..1412e9a2
--- /dev/null
+++ b/web-application/guides/index.md
@@ -0,0 +1,12 @@
+---
+layout: default
+title: Guides
+nav_order: 2
+permalink: /web-application/guides
+parent: Web Application
+has_children: true
+---
+
+# Guides
+
+This section contains detailed, task-based guides for users who want to go beyond the basics.
diff --git a/web-application/guides/monitoring.md b/web-application/guides/monitoring.md
new file mode 100644
index 00000000..298732b1
--- /dev/null
+++ b/web-application/guides/monitoring.md
@@ -0,0 +1,30 @@
+---
+layout: default
+title: Monitoring
+nav_order: 4
+permalink: /web-application/guides/monitoring
+parent: Guides
+grand_parent: Web Application
+---
+
+# Monitoring
+
+## Runtime monitoring via `GET /health_check.txt`
+
+It is recommended to set up monitoring of the `/health_check.txt` endpoint. With that, you can find out when one of _your own_ configs breaks. The endpoint uses HTTP Basic authentication.
+
+First, set the username and password via these environment variables: `HEALTH_CHECK_USERNAME` and `HEALTH_CHECK_PASSWORD`. If these are not set, html2rss-web will generate a new random username and password on _each_ start.
+
+An authenticated `GET /health_check.txt` request will respond with:
+
+- If the feeds are generatable: `success`.
+- Otherwise: the names of the broken configs.
+
+To get notified when one of your configs breaks, set up monitoring of this endpoint.
+
+[UptimeRobot's free plan](https://uptimerobot.com/) is sufficient for basic monitoring (every 5 minutes).
+Create a monitor of type _Keyword_ with this information and make it aware of your username and password.
+
+## Application Performance Monitoring using Sentry
+
+When you specify `SENTRY_DSN` in your environment variables, the application will be setup to use Sentry.
diff --git a/web-application/index.md b/web-application/index.md
new file mode 100644
index 00000000..fb775bd9
--- /dev/null
+++ b/web-application/index.md
@@ -0,0 +1,20 @@
+---
+layout: default
+title: Web Application
+nav_order: 2
+has_children: true
+permalink: /web-application
+---
+
+# html2rss-web
+
+This web application scrapes websites to build and deliver RSS 2.0 feeds.
+
+## Features
+
+*   **Stable URLs:** Provides stable URLs for feeds generated by automatic sourcing.
+*   **Custom Feeds:** Create your own custom feeds.
+*   **Included Configs:** Comes with plenty of [included configs](https://github.com/html2rss/html2rss-configs) out of the box.
+*   **Caching:** Handles request caching and sets caching-related HTTP headers.
+
+The functionality of scraping websites and building the RSS feeds is provided by the Ruby gem [`html2rss`](https://github.com/html2rss/html2rss).
diff --git a/web-application/reference/configuration.md b/web-application/reference/configuration.md
new file mode 100644
index 00000000..8430deeb
--- /dev/null
+++ b/web-application/reference/configuration.md
@@ -0,0 +1,32 @@
+---
+layout: default
+title: Configuration
+nav_order: 1
+permalink: /web-application/reference/configuration
+parent: Reference
+grand_parent: Web Application
+---
+
+# Configuration Reference
+
+## Supported ENV variables
+
+| Name | Description |
+| --- | --- |
+| `BASE_URL` | default: '<http://localhost:3000>' |
+| `LOG_LEVEL` | default: 'warn' |
+| `HEALTH_CHECK_USERNAME` | default: auto-generated on start |
+| `HEALTH_CHECK_PASSWORD` | default: auto-generated on start |
+| | |
+| `AUTO_SOURCE_ENABLED` | default: false |
+| `AUTO_SOURCE_USERNAME` | no default. |
+| `AUTO_SOURCE_PASSWORD` | no default. |
+| `AUTO_SOURCE_ALLOWED_ORIGINS` | no default. |
+| | |
+| `PORT` | default: 3000 |
+| `RACK_ENV` | default: 'development' |
+| `RACK_TIMEOUT_SERVICE_TIMEOUT` | default: 15 |
+| `WEB_CONCURRENCY` | default: 2 |
+| `WEB_MAX_THREADS` | default: 5 |
+| | |
+| `SENTRY_DSN` | no default. |
diff --git a/web-application/reference/included-configs.md b/web-application/reference/included-configs.md
new file mode 100644
index 00000000..50887bae
--- /dev/null
+++ b/web-application/reference/included-configs.md
@@ -0,0 +1,21 @@
+---
+layout: default
+title: Included Configs
+nav_order: 2
+permalink: /web-application/reference/included-configs
+parent: Reference
+grand_parent: Web Application
+---
+
+# Included Configs
+
+html2rss-web comes with many feed configs out of the box. [See the file list of all configs.](https://github.com/html2rss/html2rss-configs/tree/master/lib/html2rss/configs)
+
+To use a config from there, build the URL like this:
+
+| | |
+| --- | --- |
+| `lib/html2rss/configs/` | `domainname.tld/whatever.yml` |
+| Would become this URL: | |
+| `http://localhost:3000/` | `domainname.tld/whatever.rss` |
+| | `^^^^^^^^^^^^^^^^^^^^^^^^^^^` |
diff --git a/web-application/reference/index.md b/web-application/reference/index.md
new file mode 100644
index 00000000..d47ecb42
--- /dev/null
+++ b/web-application/reference/index.md
@@ -0,0 +1,12 @@
+---
+layout: default
+title: Reference
+nav_order: 3
+permalink: /web-application/reference
+parent: Web Application
+has_children: true
+---
+
+# Reference
+
+This section contains detailed reference material.

From 2e01979c5ba91a9a7df9b646d087ed3ec4b9f557 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 26 Jul 2025 13:53:56 +0200
Subject: [PATCH 03/17] add og meta tags

---
 _includes/head_custom.html | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/_includes/head_custom.html b/_includes/head_custom.html
index d7e49ed8..1f8f8095 100644
--- a/_includes/head_custom.html
+++ b/_includes/head_custom.html
@@ -1,10 +1,20 @@
+<meta name="mobile-web-app-capable" content="yes">
 <meta name="apple-mobile-web-app-capable" content="yes">
 <meta name="apple-mobile-web-app-status-bar-style" content="black">
 <meta name="referrer" content="no-referrer" />
+<meta name="description" content="{% if page.description %}{{ page.description | strip_html | strip_newlines | truncate: 160 }}{% else %}{{ site.description }}{% endif %}">
 <meta
   name="robots"
   content="{% if page.noindex %}noindex, noarchive, follow{% else %}index, follow{% endif %}"
 />
+
+<meta property="og:url" content="{{ page.url | replace:'index.html','' | absolute_url }}">
+<meta property="og:title" content="{% if page.title %}{{ page.title }}{% else %}{{ site.title }}{% endif %}">
+<meta property="og:description" content="{% if page.description %}{{ page.description | strip_html | strip_newlines | truncate: 160 }}{% else %}{{ site.description }}{% endif %}">
+<meta property="og:site_name" content="{{ site.title }}">
+<meta property="og:image" content="{{ '/assets/images/logo.png' | absolute_url }}">
+<meta property="og:type" content="website">
+
 <link rel="stylesheet" href="{{ '/assets/css/main.css' | relative_url }}" />
 <link rel="apple-touch-icon" sizes="180x180" href="/assets/images/apple-touch-icon.png">
 <link rel="icon" type="image/png" sizes="32x32" href="/assets/images/favicon-32x32.png">

From 15d4adacb5ff6425d46b31408909b8aea52328e2 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 26 Jul 2025 14:03:52 +0200
Subject: [PATCH 04/17] ci: setup lint job

---
 .github/dependabot.yml         | 10 +++++-----
 .github/workflows/gh-pages.yml |  4 ++--
 .github/workflows/lint.yml     | 24 ++++++++++++++++++++++++
 .prettierignore                |  3 +++
 .prettierrc.json               |  4 ++++
 .stylelintrc.json              | 20 --------------------
 Makefile                       | 17 +++++++++++++----
 package.json                   |  9 ++++++++-
 yarn.lock                      | 20 +++++++++++++++++++-
 9 files changed, 78 insertions(+), 33 deletions(-)
 create mode 100644 .github/workflows/lint.yml
 create mode 100644 .prettierignore
 create mode 100644 .prettierrc.json

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 28d65a02..ffbf8f3e 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -1,7 +1,7 @@
 version: 2
 updates:
   - package-ecosystem: bundler
-    directory: "/"
+    directory: '/'
     schedule:
       interval: weekly
     open-pull-requests-limit: 10
@@ -11,9 +11,9 @@ updates:
     groups:
       ruby:
         patterns:
-          - "*"
-  - package-ecosystem: "npm"
-    directory: "/"
+          - '*'
+  - package-ecosystem: 'npm'
+    directory: '/'
     schedule:
       interval: weekly
     allow:
@@ -21,4 +21,4 @@ updates:
     groups:
       npm:
         patterns:
-          - "*"
+          - '*'
diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
index 7b9aa833..90b5221a 100644
--- a/.github/workflows/gh-pages.yml
+++ b/.github/workflows/gh-pages.yml
@@ -51,5 +51,5 @@ jobs:
           publish_dir: ./_site
           publish_branch: master
           force_orphan: true
-          user_name: "github-actions[bot]"
-          user_email: "github-actions[bot]@users.noreply.github.com"
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
new file mode 100644
index 00000000..f54ea198
--- /dev/null
+++ b/.github/workflows/lint.yml
@@ -0,0 +1,24 @@
+name: lint
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'yarn'
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Run linters
+        run: yarn lint
diff --git a/.prettierignore b/.prettierignore
new file mode 100644
index 00000000..12024b60
--- /dev/null
+++ b/.prettierignore
@@ -0,0 +1,3 @@
+_site
+node_modules
+yarn.lock
diff --git a/.prettierrc.json b/.prettierrc.json
new file mode 100644
index 00000000..a20502b7
--- /dev/null
+++ b/.prettierrc.json
@@ -0,0 +1,4 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all"
+}
diff --git a/.stylelintrc.json b/.stylelintrc.json
index c3d6a104..2fdfa307 100644
--- a/.stylelintrc.json
+++ b/.stylelintrc.json
@@ -5,28 +5,8 @@
     "stylelint-config-recess-order"
   ],
   "rules": {
-    "function-comma-space-after": "always",
     "no-descending-specificity": null,
     "declaration-block-single-line-max-declarations": 1,
-    "unit-whitelist": [
-      "%",
-      "ch",
-      "deg",
-      "em",
-      "fr",
-      "ms",
-      "px",
-      "rem",
-      "s",
-      "turn",
-      "vh",
-      "vw"
-    ],
-    "max-empty-lines": 1,
-    "max-line-length": 110,
-    "no-empty-first-line": true,
-    "indentation": 2,
-    "number-leading-zero": "always",
     "media-feature-name-no-unknown": [
       true,
       {
diff --git a/Makefile b/Makefile
index 44ee8016..595a0c63 100644
--- a/Makefile
+++ b/Makefile
@@ -1,13 +1,22 @@
-default: setup clean fix serve
+default: setup clean lintfix serve
 
 setup:
 	yarn check || yarn
 	bundle check || bundle
 	make update
 
-fix:
-	prettier --write --no-semi "**/*.yml" "**/*.md" "**/*.scss" "assets/**/*.js"
-	yarn run stylelint --fix "assets/**/*.scss" || echo 'stylelint: found no scss files to lint'
+lint:
+	yarn lint
+	make lint-ruby
+
+lintfix:
+	yarn lintfix
+	make lintfix-ruby
+
+lint-ruby:
+	bundle exec rubocop
+
+lintfix-ruby:
 	bundle exec rubocop -a
 
 clean:
diff --git a/package.json b/package.json
index f4e07a15..8733ed55 100644
--- a/package.json
+++ b/package.json
@@ -2,11 +2,18 @@
   "license": "UNLICENSED",
   "private": true,
   "scripts": {
-    "lintfix": "stylelint --fix assets/**/*.scss"
+    "lint": "yarn lint:stylelint && yarn lint:prettier",
+    "lint:stylelint": "stylelint assets/**/*.scss",
+    "lint:prettier": "prettier --check .",
+    "lintfix": "yarn lintfix:stylelint && yarn lintfix:prettier",
+    "lintfix:stylelint": "stylelint --fix assets/**/*.scss",
+    "lintfix:prettier": "prettier --write ."
   },
   "devDependencies": {
+    "prettier": "3.3.3",
     "stylelint": "16.22.0",
     "stylelint-config-recess-order": "7.1.0",
+    "stylelint-order": "6.0.4",
     "stylelint-config-recommended-scss": "15.0.1",
     "stylelint-scss": "6.12.1"
   },
diff --git a/yarn.lock b/yarn.lock
index 35aa4cc1..d5ea367a 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -613,12 +613,17 @@ postcss-selector-parser@^7.1.0:
     cssesc "^3.0.0"
     util-deprecate "^1.0.2"
 
+postcss-sorting@^8.0.2:
+  version "8.0.2"
+  resolved "https://registry.yarnpkg.com/postcss-sorting/-/postcss-sorting-8.0.2.tgz#6393385ece272baf74bee9820fb1b58098e4eeca"
+  integrity sha512-M9dkSrmU00t/jK7rF6BZSZauA5MAaBW4i5EnJXspMwt4iqTh/L9j6fgMnbElEOfyRyfLfVbIHj/R52zHzAPe1Q==
+
 postcss-value-parser@^4.2.0:
   version "4.2.0"
   resolved "https://registry.yarnpkg.com/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz#723c09920836ba6d3e5af019f92bc0971c02e514"
   integrity sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==
 
-postcss@^8.5.6:
+postcss@^8.4.32, postcss@^8.5.6:
   version "8.5.6"
   resolved "https://registry.yarnpkg.com/postcss/-/postcss-8.5.6.tgz#2825006615a619b4f62a9e7426cc120b349a8f3c"
   integrity sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==
@@ -627,6 +632,11 @@ postcss@^8.5.6:
     picocolors "^1.1.1"
     source-map-js "^1.2.1"
 
+prettier@3.3.3:
+  version "3.3.3"
+  resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.3.3.tgz#30c54fe0be0d8d12e6ae61dbb10109ea00d53105"
+  integrity sha512-i2tDNA0O5IrMO757lfrdQZCc2jPNDVntV0m/+4whiDfWaTKfMNgR7Qz0NAeGz/nRqF4m5/6CLzbP4/liHt12Ew==
+
 punycode@^2.1.0:
   version "2.1.1"
   resolved "https://registry.yarnpkg.com/punycode/-/punycode-2.1.1.tgz#b58b010ac40c22c5657616c8d2c2c02c7bf479ec"
@@ -721,6 +731,14 @@ stylelint-config-recommended@^16.0.0:
   resolved "https://registry.yarnpkg.com/stylelint-config-recommended/-/stylelint-config-recommended-16.0.0.tgz#0221f19902816fe7d53d9a01eb0be4cc7b4fe80a"
   integrity sha512-4RSmPjQegF34wNcK1e1O3Uz91HN8P1aFdFzio90wNK9mjgAI19u5vsU868cVZboKzCaa5XbpvtTzAAGQAxpcXA==
 
+stylelint-order@6.0.4:
+  version "6.0.4"
+  resolved "https://registry.yarnpkg.com/stylelint-order/-/stylelint-order-6.0.4.tgz#3e80d876c61a98d2640de181433686f24284748b"
+  integrity sha512-0UuKo4+s1hgQ/uAxlYU4h0o0HS4NiQDud0NAUNI0aa8FJdmYHA5ZZTFHiV5FpmE3071e9pZx5j0QpVJW5zOCUA==
+  dependencies:
+    postcss "^8.4.32"
+    postcss-sorting "^8.0.2"
+
 stylelint-scss@6.12.1, stylelint-scss@^6.12.0:
   version "6.12.1"
   resolved "https://registry.yarnpkg.com/stylelint-scss/-/stylelint-scss-6.12.1.tgz#7de9980a7c9acb7a3f203498e7296526cb52ffa0"

From 6bad48a13647ef81c34c62ae87f1736afd17b830 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 26 Jul 2025 14:13:40 +0200
Subject: [PATCH 05/17] style: lintfix files

---
 .github/dependabot.yml                        |  10 +-
 .github/workflows/gh-pages.yml                |  12 +-
 .github/workflows/lint.yml                    |   8 +-
 .prettierrc.json                              |   2 +-
 _config.yml                                   |   1 -
 _includes/head_custom.html                    |  77 ++++++++---
 assets/css/sass/base.scss                     |  29 ++---
 assets/js/configs/index.js                    | 121 +++++++++---------
 assets/js/main.js                             |   6 +-
 configs/index.html                            | 103 +++++++++------
 index.md                                      |   6 +-
 ruby-gem/configuration/selectors/index.md     |   8 +-
 ruby-gem/index.md                             |   6 +-
 web-application/index.md                      |   8 +-
 web-application/reference/configuration.md    |  38 +++---
 web-application/reference/included-configs.md |  10 +-
 16 files changed, 259 insertions(+), 186 deletions(-)

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index ffbf8f3e..28d65a02 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -1,7 +1,7 @@
 version: 2
 updates:
   - package-ecosystem: bundler
-    directory: '/'
+    directory: "/"
     schedule:
       interval: weekly
     open-pull-requests-limit: 10
@@ -11,9 +11,9 @@ updates:
     groups:
       ruby:
         patterns:
-          - '*'
-  - package-ecosystem: 'npm'
-    directory: '/'
+          - "*"
+  - package-ecosystem: "npm"
+    directory: "/"
     schedule:
       interval: weekly
     allow:
@@ -21,4 +21,4 @@ updates:
     groups:
       npm:
         patterns:
-          - '*'
+          - "*"
diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
index 90b5221a..af01cbfb 100644
--- a/.github/workflows/gh-pages.yml
+++ b/.github/workflows/gh-pages.yml
@@ -8,6 +8,10 @@ on:
     branches:
       - main
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -37,6 +41,10 @@ jobs:
     runs-on: ubuntu-latest
     needs: build
     if: github.ref == 'refs/heads/main'
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
     steps:
       - name: Download artifact
         uses: actions/download-artifact@v4
@@ -51,5 +59,5 @@ jobs:
           publish_dir: ./_site
           publish_branch: master
           force_orphan: true
-          user_name: 'github-actions[bot]'
-          user_email: 'github-actions[bot]@users.noreply.github.com'
+          user_name: "github-actions[bot]"
+          user_email: "github-actions[bot]@users.noreply.github.com"
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index f54ea198..06e512b0 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -5,6 +5,10 @@ on:
     branches:
       - main
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref }}
+  cancel-in-progress: true
+
 jobs:
   lint:
     runs-on: ubuntu-latest
@@ -14,8 +18,8 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
-          cache: 'yarn'
+          node-version: "24"
+          cache: "yarn"
 
       - name: Install dependencies
         run: yarn install --frozen-lockfile
diff --git a/.prettierrc.json b/.prettierrc.json
index a20502b7..f3bcd4c9 100644
--- a/.prettierrc.json
+++ b/.prettierrc.json
@@ -1,4 +1,4 @@
 {
-  "singleQuote": true,
+  "singleQuote": false,
   "trailingComma": "all"
 }
diff --git a/_config.yml b/_config.yml
index 201a1553..2b4b1444 100644
--- a/_config.yml
+++ b/_config.yml
@@ -24,7 +24,6 @@ aux_links:
   "GitHub":
     - "https://github.com/html2rss"
 
-
 # Footer "Edit this page on GitHub" link text
 gh_edit_link: true # show or hide edit this page link
 gh_edit_link_text: "Edit this page on GitHub."
diff --git a/_includes/head_custom.html b/_includes/head_custom.html
index 1f8f8095..d2c8e1c3 100644
--- a/_includes/head_custom.html
+++ b/_includes/head_custom.html
@@ -1,28 +1,65 @@
-<meta name="mobile-web-app-capable" content="yes">
-<meta name="apple-mobile-web-app-capable" content="yes">
-<meta name="apple-mobile-web-app-status-bar-style" content="black">
+<meta name="mobile-web-app-capable" content="yes" />
+<meta name="apple-mobile-web-app-capable" content="yes" />
+<meta name="apple-mobile-web-app-status-bar-style" content="black" />
 <meta name="referrer" content="no-referrer" />
-<meta name="description" content="{% if page.description %}{{ page.description | strip_html | strip_newlines | truncate: 160 }}{% else %}{{ site.description }}{% endif %}">
+<meta
+  name="description"
+  content="{% if page.description %}{{ page.description | strip_html | strip_newlines | truncate: 160 }}{% else %}{{ site.description }}{% endif %}"
+/>
 <meta
   name="robots"
   content="{% if page.noindex %}noindex, noarchive, follow{% else %}index, follow{% endif %}"
 />
 
-<meta property="og:url" content="{{ page.url | replace:'index.html','' | absolute_url }}">
-<meta property="og:title" content="{% if page.title %}{{ page.title }}{% else %}{{ site.title }}{% endif %}">
-<meta property="og:description" content="{% if page.description %}{{ page.description | strip_html | strip_newlines | truncate: 160 }}{% else %}{{ site.description }}{% endif %}">
-<meta property="og:site_name" content="{{ site.title }}">
-<meta property="og:image" content="{{ '/assets/images/logo.png' | absolute_url }}">
-<meta property="og:type" content="website">
+<meta
+  property="og:url"
+  content="{{ page.url | replace:'index.html','' | absolute_url }}"
+/>
+<meta
+  property="og:title"
+  content="{% if page.title %}{{ page.title }}{% else %}{{ site.title }}{% endif %}"
+/>
+<meta
+  property="og:description"
+  content="{% if page.description %}{{ page.description | strip_html | strip_newlines | truncate: 160 }}{% else %}{{ site.description }}{% endif %}"
+/>
+<meta property="og:site_name" content="{{ site.title }}" />
+<meta
+  property="og:image"
+  content="{{ '/assets/images/logo.png' | absolute_url }}"
+/>
+<meta property="og:type" content="website" />
 
 <link rel="stylesheet" href="{{ '/assets/css/main.css' | relative_url }}" />
-<link rel="apple-touch-icon" sizes="180x180" href="/assets/images/apple-touch-icon.png">
-<link rel="icon" type="image/png" sizes="32x32" href="/assets/images/favicon-32x32.png">
-<link rel="icon" type="image/png" sizes="16x16" href="/assets/images/favicon-16x16.png">
-<link rel="manifest" href="/assets/images/site.webmanifest">
-<link rel="mask-icon" href="/assets/images/safari-pinned-tab.svg" color="#111111">
-<link rel="shortcut icon" href="/assets/images/favicon.ico">
-<meta name="msapplication-TileColor" content="#111111">
-<meta name="msapplication-config" content="/assets/images/browserconfig.xml">
-<meta name="theme-color" content="#111111">
-<script data-goatcounter="https://html2rss.goatcounter.com/count" async src="//gc.zgo.at/count.js"></script>
+<link
+  rel="apple-touch-icon"
+  sizes="180x180"
+  href="/assets/images/apple-touch-icon.png"
+/>
+<link
+  rel="icon"
+  type="image/png"
+  sizes="32x32"
+  href="/assets/images/favicon-32x32.png"
+/>
+<link
+  rel="icon"
+  type="image/png"
+  sizes="16x16"
+  href="/assets/images/favicon-16x16.png"
+/>
+<link rel="manifest" href="/assets/images/site.webmanifest" />
+<link
+  rel="mask-icon"
+  href="/assets/images/safari-pinned-tab.svg"
+  color="#111111"
+/>
+<link rel="shortcut icon" href="/assets/images/favicon.ico" />
+<meta name="msapplication-TileColor" content="#111111" />
+<meta name="msapplication-config" content="/assets/images/browserconfig.xml" />
+<meta name="theme-color" content="#111111" />
+<script
+  data-goatcounter="https://html2rss.goatcounter.com/count"
+  async
+  src="//gc.zgo.at/count.js"
+></script>
diff --git a/assets/css/sass/base.scss b/assets/css/sass/base.scss
index 14c8977c..9e59fecc 100644
--- a/assets/css/sass/base.scss
+++ b/assets/css/sass/base.scss
@@ -17,18 +17,18 @@
 }
 
 #configs input {
+  box-sizing: border-box;
   width: 100%;
   padding: var(--spacing-xs);
-  box-sizing: border-box;
-  line-height: var(--line-height-base);
+  font-family: var(--font-family-mono);
   font-size: var(--font-size-base);
+  line-height: var(--line-height-base);
   color: var(--color-text);
-  font-family: var(--font-family-mono);
+  appearance: none;
+  outline: none;
   background-color: transparent;
   border: 0;
   border-radius: 0;
-  outline: none;
-  appearance: none;
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
 }
@@ -36,16 +36,15 @@
 .config__headline > span,
 .config__url {
   hyphens: none;
-  word-break: break-word;
-  overflow-wrap: break-word;
   text-wrap: wrap;
+  overflow-wrap: break-word;
 }
 
 .config__url em {
   padding-right: 0.125em;
+  font-style: italic;
   letter-spacing: -0.05em;
   opacity: 0.75;
-  font-style: italic;
 }
 
 .config__url .config__url-amp:last-child {
@@ -58,9 +57,9 @@
   left: 0;
   width: 0;
   height: 0;
-  opacity: 0;
   pointer-events: none;
   user-select: text;
+  opacity: 0;
 }
 
 .js__copy-element::selection {
@@ -68,22 +67,22 @@
 }
 
 .noscript {
+  padding: var(--spacing-sm);
   font-weight: 600;
   color: var(--color-error);
   background: var(--color-error-bg);
-  padding: var(--spacing-sm);
   border: 1px solid var(--color-error);
 }
 
 button[data-bind-click="copy"] {
   padding: var(--button-padding-y) var(--button-padding-x);
-  border: 2px solid transparent;
-  border-radius: var(--border-radius-sm);
-  background-color: #fff;
-  color: var(--color-text);
-  cursor: pointer;
   font: inherit;
   line-height: 1.2;
+  color: var(--color-text);
+  cursor: pointer;
+  background-color: #fff;
+  border: 2px solid transparent;
+  border-radius: var(--border-radius-sm);
   transition: var(--transition-border), var(--transition-shadow);
 }
 
diff --git a/assets/js/configs/index.js b/assets/js/configs/index.js
index b9deaa32..e02ebaac 100644
--- a/assets/js/configs/index.js
+++ b/assets/js/configs/index.js
@@ -1,59 +1,66 @@
-;(() => {
-  const instanceEl = document.querySelector('input[name="instance"]')
-
-  function instanceUrl() {
-    const url = instanceEl.value
-
-    return url.substr(-1) === "/" ? url : `${url}/`
-  }
-
-  function onChangeInstanceUrl() {
-    const url = instanceUrl()
-
-    Array.from(document.querySelectorAll(".instance")).forEach((el) => {
-      el.innerText = url
-    })
-  }
-
-  function onShowClick({ target }) {
-    target.href = [instanceUrl(), target.dataset.path].join("")
-    return false
-  }
-
-  function onCopyClick({ target }) {
-    const href = [instanceUrl(), target.dataset.path].join("")
-    const el = document.createElement("span")
-    el.classList.add("js__copy-element")
-    el.innerText = href
-
-    document.body.appendChild(el)
-    copyElementContents(el, target)
-    return false
-  }
-
-  function copyElementContents(el, triggerEl) {
-    el.focus()
-    window.getSelection().selectAllChildren(el)
-    document.execCommand("copy")
-
-    triggerEl.classList.add("copied")
-    window.setTimeout(() => {
-      el.blur()
-      el.remove()
-      triggerEl.classList.remove("copied")
-      triggerEl.blur()
-    }, 1000)
-  }
-
-  // init
-  document.querySelector("#configs").addEventListener("click", (event) => {
-    if (event.target.dataset.bindClick === "show") {
-      return onShowClick(event)
-    } else if (event.target.dataset.bindClick === "copy") {
-      return onCopyClick(event)
+const App = {
+  init() {
+    this.instanceEl = document.querySelector('input[name="instance"]');
+    if (!this.instanceEl) return;
+
+    this.configsEl = document.querySelector("#configs");
+    this.bindEvents();
+    this.updateInstanceUrl();
+  },
+
+  bindEvents() {
+    this.configsEl.addEventListener("click", (event) => {
+      const { bindClick } = event.target.dataset;
+      if (bindClick === "show") {
+        this.handleShowClick(event);
+      } else if (bindClick === "copy") {
+        this.handleCopyClick(event);
+      }
+    });
+
+    this.instanceEl.addEventListener("blur", this.updateInstanceUrl.bind(this));
+  },
+
+  getInstanceUrl() {
+    const url = this.instanceEl.value;
+    return url.endsWith("/") ? url : `${url}/`;
+  },
+
+  updateInstanceUrl() {
+    const url = this.getInstanceUrl();
+    document.querySelectorAll(".instance").forEach((el) => {
+      if (el instanceof HTMLElement) {
+        el.innerText = url;
+      }
+    });
+  },
+
+  handleShowClick(event) {
+    const { target } = event;
+    target.href = `${this.getInstanceUrl()}${target.dataset.path}`;
+  },
+
+  async handleCopyClick(event) {
+    const { target } = event;
+    const href = `${this.getInstanceUrl()}${target.dataset.path}`;
+
+    try {
+      await navigator.clipboard.writeText(href);
+      this.showCopiedState(target);
+    } catch (err) {
+      console.error("Failed to copy: ", err);
     }
-  })
+  },
+
+  showCopiedState(triggerEl) {
+    triggerEl.classList.add("copied");
+    setTimeout(() => {
+      triggerEl.classList.remove("copied");
+      triggerEl.blur();
+    }, 1000);
+  },
+};
 
-  instanceEl.addEventListener("blur", onChangeInstanceUrl)
-  onChangeInstanceUrl()
-})()
+document.addEventListener("DOMContentLoaded", () => {
+  App.init();
+});
diff --git a/assets/js/main.js b/assets/js/main.js
index a4385c4b..2f7bb21c 100644
--- a/assets/js/main.js
+++ b/assets/js/main.js
@@ -7,8 +7,8 @@
 //   async
 // ></script>
 
-;(() => {
+(() => {
   document.addEventListener("DOMContentLoaded", () => {
     // do stuff
-  })
-})()
+  });
+})();
diff --git a/configs/index.html b/configs/index.html
index a762539e..f5c8d9fd 100644
--- a/configs/index.html
+++ b/configs/index.html
@@ -15,35 +15,44 @@
   <fieldset class="mb-4 py-1 px-2">
     <legend class="fs-5">Instance URL</legend>
 
-    <input type="text" name="instance" value="https://1.h2r.workers.dev" class="bg-grey-dk-100 p-2">
+    <input
+      type="text"
+      name="instance"
+      value="https://1.h2r.workers.dev"
+      class="bg-grey-dk-100 p-2"
+    />
   </fieldset>
 
   <p class="fs-4">
     Find publicly available instances in the
-    <a href="https://github.com/html2rss/html2rss-web/wiki/Instances"
-       target="_blank"
-       >wiki</a>
+    <a
+      href="https://github.com/html2rss/html2rss-web/wiki/Instances"
+      target="_blank"
+      >wiki</a
+    >
     or
-    <a href="https://github.com/html2rss/html2rss-web"
-       target="_blank"
-       >host your own</a>.
+    <a href="https://github.com/html2rss/html2rss-web" target="_blank"
+      >host your own</a
+    >.
   </p>
 
   {% for config in site.data.configs %}
   <details class="py-1 px-2">
     <summary class="config__headline text-mono">
-      <span>{{ config.domain }}</span
-      ><span class="text-yellow-300">/</span
+      <span>{{ config.domain }}</span><span class="text-yellow-300">/</span
       ><span>{{ config.name }}</span>
 
-       {%- if config.valid_channel_url -%}
-      <a href="#"
+      {%- if config.valid_channel_url -%}
+      <a
+        href="#"
         data-bind-click="show"
         data-path="{{ config.domain }}/{{ config.name }}.rss"
         class="float-right"
         rel="noopener noreferrer"
-        > RSS</a>
-        {% endif %}
+      >
+        RSS</a
+      >
+      {% endif %}
     </summary>
 
     <dl>
@@ -51,23 +60,21 @@
       <dt>URL to scrape</dt>
       <dd>
         {%- if config.valid_channel_url -%}
-        <a href="{{ config.channel.url }}"
-           class="config__url"
-           target="_blank"
-           rel="noopener noreferrer"
-           >{{ config.channel.url }}</a>
+        <a
+          href="{{ config.channel.url }}"
+          class="config__url"
+          target="_blank"
+          rel="noopener noreferrer"
+          >{{ config.channel.url }}</a
+        >
         {%- else -%}
-          <span class="config__url">{{ config.channel.url | xml_escape }}</span>
+        <span class="config__url">{{ config.channel.url | xml_escape }}</span>
         {%- endif -%}
       </dd>
-      {%- endif -%}
-
-      {%- if config.channel.time_zone -%}
+      {%- endif -%} {%- if config.channel.time_zone -%}
       <dt>Time zone</dt>
       <dd>{{ config.channel.time_zone }}</dd>
-      {%- endif -%}
-
-      {%- if config.channel.language -%}
+      {%- endif -%} {%- if config.channel.language -%}
       <dt>Language</dt>
       <dd>{{ config.channel.language }}</dd>
       {%- endif -%}
@@ -75,40 +82,52 @@
 
     {%- if config.valid_channel_url -%}
     <div>
-      <a href="#"
+      <a
+        href="#"
         data-bind-click="show"
         data-path="{{ config.domain }}/{{ config.name }}.rss"
         class="btn btn-primary fs-3 mb-4 mr-2 v-align-middle"
         rel="noopener noreferrer"
-        >Show RSS</a>
+        >Show RSS</a
+      >
 
       <button
         data-bind-click="copy"
         data-path="{{ config.domain }}/{{ config.name }}.rss"
         class="btn fs-3 mb-4 mr-2 v-align-middle"
         rel="noopener noreferrer"
-        >Copy URL</button>
+      >
+        Copy URL
+      </button>
 
-      <a href="https://github.com/html2rss/html2rss-configs/blob/master/lib/html2rss/configs/{{ config.domain }}/{{ config.name }}.yml"
-        class="btn fs-3 mb-4 v-align-middle">
+      <a
+        href="https://github.com/html2rss/html2rss-configs/blob/master/lib/html2rss/configs/{{ config.domain }}/{{ config.name }}.yml"
+        class="btn fs-3 mb-4 v-align-middle"
+      >
         View on Github
       </a>
     </div>
     {%- else -%}
-      <p class="bg-grey-dk-200 text-red-300 p-2">
-        This config requires parameters to work.<br>
-        <a href="https://github.com/html2rss/html2rss-configs/blob/master/lib/html2rss/configs/{{ config.domain }}/{{ config.name }}.yml">View the config</a>
-        to find out which values are possible.
-        <br>
-        <code class="d-block w-100 py-2 bg-grey-dk-300 text-grey-dk-000 fs-4">
-          <span class="config__url"
-          ><span class="instance"></span>{{ config.domain }}/{{ config.name }}.rss?{% for params in config.url_parameters %}{{ params[0] }}=<em>{{ params[1] }}</em><span class="config__url-amp">&</span>{% endfor %}
-          </span>
-        </code>
-      </p>
+    <p class="bg-grey-dk-200 text-red-300 p-2">
+      This config requires parameters to work.<br />
+      <a
+        href="https://github.com/html2rss/html2rss-configs/blob/master/lib/html2rss/configs/{{ config.domain }}/{{ config.name }}.yml"
+        >View the config</a
+      >
+      to find out which values are possible.
+      <br />
+      <code class="d-block w-100 py-2 bg-grey-dk-300 text-grey-dk-000 fs-4">
+        <span class="config__url"
+          ><span class="instance"></span>{{ config.domain }}/{{ config.name
+          }}.rss?{% for params in config.url_parameters %}{{ params[0] }}=<em
+            >{{ params[1] }}</em
+          ><span class="config__url-amp">&</span>{% endfor %}
+        </span>
+      </code>
+    </p>
     {%- endif -%}
   </details>
-{% endfor %}
+  {% endfor %}
 </div>
 
 <script src="/assets/js/configs/index.js" async defer></script>
diff --git a/index.md b/index.md
index d2a2a83b..60105d55 100644
--- a/index.md
+++ b/index.md
@@ -16,9 +16,9 @@ Tired of missing updates from websites that don't offer RSS feeds? `html2rss` is
 
 `html2rss` is a suite of tools designed to help you create and manage RSS feeds.
 
-*   **[html2rss-web]({{ '/web-application' | relative_url }}):** A user-friendly web application that makes it easy to create, manage, and share RSS feeds. This is the recommended starting point for most users.
-*   **[html2rss (Ruby Gem)]({{ '/ruby-gem' | relative_url }}):** The core library that powers the web application. It provides a powerful and flexible command-line interface for creating custom RSS feeds.
-*   **[html2rss-configs](https://github.com/html2rss/html2rss-configs):** A community-driven repository of pre-built feed configurations for popular websites.
+- **[html2rss-web]({{ '/web-application' | relative_url }}):** A user-friendly web application that makes it easy to create, manage, and share RSS feeds. This is the recommended starting point for most users.
+- **[html2rss (Ruby Gem)]({{ '/ruby-gem' | relative_url }}):** The core library that powers the web application. It provides a powerful and flexible command-line interface for creating custom RSS feeds.
+- **[html2rss-configs](https://github.com/html2rss/html2rss-configs):** A community-driven repository of pre-built feed configurations for popular websites.
 
 ---
 
diff --git a/ruby-gem/configuration/selectors/index.md b/ruby-gem/configuration/selectors/index.md
index da7c4dcb..9fcf573b 100644
--- a/ruby-gem/configuration/selectors/index.md
+++ b/ruby-gem/configuration/selectors/index.md
@@ -65,10 +65,10 @@ The following selectors can be used to extract content for the RSS feed:
 
 Each selector can have the following attributes:
 
-| Name           | Value                                                                                                   |
-| :------------- | :------------------------------------------------------------------------------------------------------ |
-| `selector`     | The CSS selector to select the element with the information.                                            |
-| `extractor`    | The name of the extractor to use. See [Extractors]({{ '/ruby-gem/configuration/selectors/extractors' | relative_url }}).               |
+| Name           | Value                                                                                                              |
+| :------------- | :----------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `selector`     | The CSS selector to select the element with the information.                                                       |
+| `extractor`    | The name of the extractor to use. See [Extractors]({{ '/ruby-gem/configuration/selectors/extractors'               | relative_url }}). |
 | `post_process` | An array of post processors to apply. See [Post Processors]({{ '/ruby-gem/configuration/selectors/post-processors' | relative_url }}). |
 
 ---
diff --git a/ruby-gem/index.md b/ruby-gem/index.md
index f951d6a9..358e30fc 100644
--- a/ruby-gem/index.md
+++ b/ruby-gem/index.md
@@ -14,6 +14,6 @@ If you are looking for the easiest way to get started with `html2rss`, we recomm
 
 This documentation is for developers who want to:
 
-*   Use the `html2rss` gem directly from the command line.
-*   Integrate the `html2rss` gem into their own Ruby applications.
-*   Contribute to the development of `html2rss`.
+- Use the `html2rss` gem directly from the command line.
+- Integrate the `html2rss` gem into their own Ruby applications.
+- Contribute to the development of `html2rss`.
diff --git a/web-application/index.md b/web-application/index.md
index fb775bd9..f141d301 100644
--- a/web-application/index.md
+++ b/web-application/index.md
@@ -12,9 +12,9 @@ This web application scrapes websites to build and deliver RSS 2.0 feeds.
 
 ## Features
 
-*   **Stable URLs:** Provides stable URLs for feeds generated by automatic sourcing.
-*   **Custom Feeds:** Create your own custom feeds.
-*   **Included Configs:** Comes with plenty of [included configs](https://github.com/html2rss/html2rss-configs) out of the box.
-*   **Caching:** Handles request caching and sets caching-related HTTP headers.
+- **Stable URLs:** Provides stable URLs for feeds generated by automatic sourcing.
+- **Custom Feeds:** Create your own custom feeds.
+- **Included Configs:** Comes with plenty of [included configs](https://github.com/html2rss/html2rss-configs) out of the box.
+- **Caching:** Handles request caching and sets caching-related HTTP headers.
 
 The functionality of scraping websites and building the RSS feeds is provided by the Ruby gem [`html2rss`](https://github.com/html2rss/html2rss).
diff --git a/web-application/reference/configuration.md b/web-application/reference/configuration.md
index 8430deeb..de28add6 100644
--- a/web-application/reference/configuration.md
+++ b/web-application/reference/configuration.md
@@ -11,22 +11,22 @@ grand_parent: Web Application
 
 ## Supported ENV variables
 
-| Name | Description |
-| --- | --- |
-| `BASE_URL` | default: '<http://localhost:3000>' |
-| `LOG_LEVEL` | default: 'warn' |
-| `HEALTH_CHECK_USERNAME` | default: auto-generated on start |
-| `HEALTH_CHECK_PASSWORD` | default: auto-generated on start |
-| | |
-| `AUTO_SOURCE_ENABLED` | default: false |
-| `AUTO_SOURCE_USERNAME` | no default. |
-| `AUTO_SOURCE_PASSWORD` | no default. |
-| `AUTO_SOURCE_ALLOWED_ORIGINS` | no default. |
-| | |
-| `PORT` | default: 3000 |
-| `RACK_ENV` | default: 'development' |
-| `RACK_TIMEOUT_SERVICE_TIMEOUT` | default: 15 |
-| `WEB_CONCURRENCY` | default: 2 |
-| `WEB_MAX_THREADS` | default: 5 |
-| | |
-| `SENTRY_DSN` | no default. |
+| Name                           | Description                        |
+| ------------------------------ | ---------------------------------- |
+| `BASE_URL`                     | default: '<http://localhost:3000>' |
+| `LOG_LEVEL`                    | default: 'warn'                    |
+| `HEALTH_CHECK_USERNAME`        | default: auto-generated on start   |
+| `HEALTH_CHECK_PASSWORD`        | default: auto-generated on start   |
+|                                |                                    |
+| `AUTO_SOURCE_ENABLED`          | default: false                     |
+| `AUTO_SOURCE_USERNAME`         | no default.                        |
+| `AUTO_SOURCE_PASSWORD`         | no default.                        |
+| `AUTO_SOURCE_ALLOWED_ORIGINS`  | no default.                        |
+|                                |                                    |
+| `PORT`                         | default: 3000                      |
+| `RACK_ENV`                     | default: 'development'             |
+| `RACK_TIMEOUT_SERVICE_TIMEOUT` | default: 15                        |
+| `WEB_CONCURRENCY`              | default: 2                         |
+| `WEB_MAX_THREADS`              | default: 5                         |
+|                                |                                    |
+| `SENTRY_DSN`                   | no default.                        |
diff --git a/web-application/reference/included-configs.md b/web-application/reference/included-configs.md
index 50887bae..04e9d951 100644
--- a/web-application/reference/included-configs.md
+++ b/web-application/reference/included-configs.md
@@ -13,9 +13,9 @@ html2rss-web comes with many feed configs out of the box. [See the file list of
 
 To use a config from there, build the URL like this:
 
-| | |
-| --- | --- |
-| `lib/html2rss/configs/` | `domainname.tld/whatever.yml` |
-| Would become this URL: | |
+|                          |                               |
+| ------------------------ | ----------------------------- |
+| `lib/html2rss/configs/`  | `domainname.tld/whatever.yml` |
+| Would become this URL:   |                               |
 | `http://localhost:3000/` | `domainname.tld/whatever.rss` |
-| | `^^^^^^^^^^^^^^^^^^^^^^^^^^^` |
+|                          | `^^^^^^^^^^^^^^^^^^^^^^^^^^^` |

From 7632b4e48ea51a6fbb34fc11829705a695f16671 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 26 Jul 2025 15:29:32 +0200
Subject: [PATCH 06/17] feat: improve listing of configs [wip]

---
 _includes/head_custom.html                    |  10 +
 assets/css/sass/base.scss                     | 103 +++++---
 assets/js/configs/index.js                    |  66 -----
 assets/js/feed-directory/index.js             | 171 +++++++++++++
 configs.md                                    |  13 +
 configs/index.html                            | 133 ----------
 feed-directory/index.html                     | 228 ++++++++++++++++++
 web-application/contributing/index.md         |  15 --
 web-application/index.md                      |   2 +-
 web-application/reference/included-configs.md |  21 --
 10 files changed, 493 insertions(+), 269 deletions(-)
 delete mode 100644 assets/js/configs/index.js
 create mode 100644 assets/js/feed-directory/index.js
 create mode 100644 configs.md
 delete mode 100644 configs/index.html
 create mode 100644 feed-directory/index.html
 delete mode 100644 web-application/contributing/index.md
 delete mode 100644 web-application/reference/included-configs.md

diff --git a/_includes/head_custom.html b/_includes/head_custom.html
index d2c8e1c3..1f8e9070 100644
--- a/_includes/head_custom.html
+++ b/_includes/head_custom.html
@@ -63,3 +63,13 @@
   async
   src="//gc.zgo.at/count.js"
 ></script>
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none">
+  <symbol id="copy-icon" viewBox="0 0 16 16">
+    <path
+      d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"
+    />
+    <path
+      d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zM9 2H7v.5a.5.5 0 0 0 .5.5h1a.5.5 0 0 0 .5-.5V2z"
+    />
+  </symbol>
+</svg>
diff --git a/assets/css/sass/base.scss b/assets/css/sass/base.scss
index 9e59fecc..0b12a7e5 100644
--- a/assets/css/sass/base.scss
+++ b/assets/css/sass/base.scss
@@ -16,39 +16,9 @@
   --transition-shadow: box-shadow 0.2s ease-in-out;
 }
 
-#configs input {
-  box-sizing: border-box;
+#configs input[name="instance"],
+#configs input[name="search"] {
   width: 100%;
-  padding: var(--spacing-xs);
-  font-family: var(--font-family-mono);
-  font-size: var(--font-size-base);
-  line-height: var(--line-height-base);
-  color: var(--color-text);
-  appearance: none;
-  outline: none;
-  background-color: transparent;
-  border: 0;
-  border-radius: 0;
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
-}
-
-.config__headline > span,
-.config__url {
-  hyphens: none;
-  text-wrap: wrap;
-  overflow-wrap: break-word;
-}
-
-.config__url em {
-  padding-right: 0.125em;
-  font-style: italic;
-  letter-spacing: -0.05em;
-  opacity: 0.75;
-}
-
-.config__url .config__url-amp:last-child {
-  display: none !important;
 }
 
 .js__copy-element {
@@ -80,7 +50,6 @@ button[data-bind-click="copy"] {
   line-height: 1.2;
   color: var(--color-text);
   cursor: pointer;
-  background-color: #fff;
   border: 2px solid transparent;
   border-radius: var(--border-radius-sm);
   transition: var(--transition-border), var(--transition-shadow);
@@ -97,3 +66,71 @@ button[data-bind-click="copy"].copied:active {
   border-color: var(--color-accent);
   box-shadow: inset 0 2px 4px var(--color-accent-bg);
 }
+
+.card-deck {
+  display: flex;
+  flex-wrap: wrap;
+}
+
+.card {
+  width: 100%;
+}
+.card-header {
+  padding: 0.75rem 1.25rem;
+  margin-bottom: 0;
+  background-color: var(--table-background-color);
+  border-bottom: 1px solid var(--border-color);
+  position: relative;
+}
+
+.card-body {
+  padding: 1.25rem;
+}
+.badge {
+  position: absolute;
+  right: 0;
+  animation: 0;
+
+  display: inline-block;
+  padding: 0.2em 0.4em;
+  font-size: 75%;
+  border-radius: 0.25rem;
+  vertical-align: middle;
+  white-space: nowrap;
+}
+
+.btn-icon {
+  padding: 0.1rem 0.2rem;
+  font-size: 0.8rem;
+  line-height: 1;
+  border-radius: var(--border-radius);
+  background-color: transparent;
+  border: 1px solid transparent;
+  color: var(--link-color);
+}
+
+.btn-icon svg {
+  width: 1em;
+  height: 1em;
+  vertical-align: -0.125em;
+  fill: currentColor;
+}
+
+.d-flex-justify-content-between {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+details {
+  transition: all 0.2s ease-in-out;
+}
+
+summary {
+  cursor: pointer;
+  outline: none;
+}
+
+summary:hover {
+  color: var(--link-color);
+}
diff --git a/assets/js/configs/index.js b/assets/js/configs/index.js
deleted file mode 100644
index e02ebaac..00000000
--- a/assets/js/configs/index.js
+++ /dev/null
@@ -1,66 +0,0 @@
-const App = {
-  init() {
-    this.instanceEl = document.querySelector('input[name="instance"]');
-    if (!this.instanceEl) return;
-
-    this.configsEl = document.querySelector("#configs");
-    this.bindEvents();
-    this.updateInstanceUrl();
-  },
-
-  bindEvents() {
-    this.configsEl.addEventListener("click", (event) => {
-      const { bindClick } = event.target.dataset;
-      if (bindClick === "show") {
-        this.handleShowClick(event);
-      } else if (bindClick === "copy") {
-        this.handleCopyClick(event);
-      }
-    });
-
-    this.instanceEl.addEventListener("blur", this.updateInstanceUrl.bind(this));
-  },
-
-  getInstanceUrl() {
-    const url = this.instanceEl.value;
-    return url.endsWith("/") ? url : `${url}/`;
-  },
-
-  updateInstanceUrl() {
-    const url = this.getInstanceUrl();
-    document.querySelectorAll(".instance").forEach((el) => {
-      if (el instanceof HTMLElement) {
-        el.innerText = url;
-      }
-    });
-  },
-
-  handleShowClick(event) {
-    const { target } = event;
-    target.href = `${this.getInstanceUrl()}${target.dataset.path}`;
-  },
-
-  async handleCopyClick(event) {
-    const { target } = event;
-    const href = `${this.getInstanceUrl()}${target.dataset.path}`;
-
-    try {
-      await navigator.clipboard.writeText(href);
-      this.showCopiedState(target);
-    } catch (err) {
-      console.error("Failed to copy: ", err);
-    }
-  },
-
-  showCopiedState(triggerEl) {
-    triggerEl.classList.add("copied");
-    setTimeout(() => {
-      triggerEl.classList.remove("copied");
-      triggerEl.blur();
-    }, 1000);
-  },
-};
-
-document.addEventListener("DOMContentLoaded", () => {
-  App.init();
-});
diff --git a/assets/js/feed-directory/index.js b/assets/js/feed-directory/index.js
new file mode 100644
index 00000000..6e380bcc
--- /dev/null
+++ b/assets/js/feed-directory/index.js
@@ -0,0 +1,171 @@
+const App = {
+  init() {
+    this.instanceEl = document.querySelector('input[name="instance"]');
+    if (!this.instanceEl) return;
+
+    this.searchEl = document.querySelector('input[name="search"]');
+    this.configsEl = document.querySelector("#configs");
+    this.cards = this.configsEl.querySelectorAll(".card");
+    this.bindEvents();
+    this.updateInstanceUrl();
+    this.initDynamicForms();
+  },
+
+  bindEvents() {
+    this.searchEl.addEventListener("input", this.filterConfigs.bind(this));
+    this.configsEl.addEventListener("click", (event) => {
+      const { bindClick } = event.target.dataset;
+      if (bindClick === "show") {
+        this.handleShowClick(event);
+      } else if (bindClick === "copy") {
+        this.handleCopyClick(event);
+      }
+    });
+
+    this.instanceEl.addEventListener("blur", this.updateInstanceUrl.bind(this));
+  },
+
+  filterConfigs() {
+    const query = this.searchEl.value.toLowerCase();
+    this.cards.forEach((card) => {
+      const title = card.querySelector(".card-title").innerText.toLowerCase();
+      if (title.includes(query)) {
+        card.style.display = "";
+      } else {
+        card.style.display = "none";
+      }
+    });
+  },
+
+  getInstanceUrl() {
+    const url = this.instanceEl.value;
+    return url.endsWith("/") ? url : `${url}/`;
+  },
+
+  updateInstanceUrl() {
+    const url = this.getInstanceUrl();
+    document.querySelectorAll(".instance").forEach((el) => {
+      if (el instanceof HTMLElement) {
+        el.innerText = url;
+      }
+    });
+  },
+
+  handleShowClick(event) {
+    const { target } = event;
+    const path = this.getPath(target);
+    if (path) {
+      target.href = `${this.getInstanceUrl()}${path}`;
+    } else {
+      event.preventDefault();
+    }
+  },
+
+  async handleCopyClick(event) {
+    const { target } = event;
+    const path = this.getPath(target);
+    if (!path) return;
+
+    const href = `${this.getInstanceUrl()}${path}`;
+
+    try {
+      await navigator.clipboard.writeText(href);
+      this.showCopiedState(target);
+    } catch (err) {
+      console.error("Failed to copy: ", err);
+    }
+  },
+
+  showCopiedState(triggerEl) {
+    triggerEl.classList.add("copied");
+    setTimeout(() => {
+      triggerEl.classList.remove("copied");
+      triggerEl.blur();
+    }, 1000);
+  },
+
+  initDynamicForms() {
+    document
+      .querySelectorAll("[data-dynamic-form]")
+      .forEach((formContainer) => {
+        const form = formContainer.querySelector("form");
+        const pathPreview = formContainer.querySelector("[data-path-preview]");
+        const actionButtons = formContainer.querySelectorAll(
+          "[data-path-template]",
+        );
+
+        if (!form || !pathPreview || !(pathPreview instanceof HTMLElement))
+          return;
+
+        const updateDynamicPath = () => {
+          const formData = new FormData(form);
+          const firstButton = actionButtons[0];
+          if (!(firstButton instanceof HTMLElement)) return;
+
+          let pathTemplate = firstButton.dataset.pathTemplate || "";
+          let pathPreviewTemplate = pathTemplate;
+
+          for (const [key, value] of formData.entries()) {
+            if (typeof value === "string") {
+              const placeholder = `{${key}}`;
+              pathTemplate = pathTemplate.replace(
+                placeholder,
+                encodeURIComponent(value),
+              );
+              pathPreviewTemplate = pathPreviewTemplate.replace(
+                placeholder,
+                value || `{${key}}`,
+              );
+            }
+          }
+
+          actionButtons.forEach((button) => {
+            if (button instanceof HTMLElement) {
+              button.dataset.path = pathTemplate;
+            }
+          });
+          pathPreview.innerText = pathPreviewTemplate;
+        };
+
+        form.addEventListener("input", updateDynamicPath);
+        updateDynamicPath(); // Initial update
+      });
+  },
+
+  getPath(target) {
+    if (!(target instanceof HTMLElement)) return null;
+
+    if (target.dataset.path) {
+      return target.dataset.path;
+    }
+
+    if (target.dataset.pathTemplate) {
+      const formContainer = target.closest("[data-dynamic-form]");
+      if (!formContainer) return null;
+
+      const form = formContainer.querySelector("form");
+      if (!form) return null;
+
+      const formData = new FormData(form);
+      let path = target.dataset.pathTemplate;
+      let allParamsFilled = true;
+
+      for (const [key, value] of formData.entries()) {
+        if (!value) {
+          allParamsFilled = false;
+        }
+        if (typeof value === "string") {
+          path = path.replace(`{${key}}`, encodeURIComponent(value));
+        }
+      }
+
+      return allParamsFilled ? path : null;
+    }
+
+    return null;
+  },
+};
+
+document.addEventListener("DOMContentLoaded", () => {
+  App.init();
+});
diff --git a/configs.md b/configs.md
new file mode 100644
index 00000000..b1cab598
--- /dev/null
+++ b/configs.md
@@ -0,0 +1,13 @@
+---
+permalink: /configs/
+---
+
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="refresh" content="0; url=/feed-directory/" />
+</head>
+<body>
+  <p>If you are not redirected automatically, follow this <a href="/feed-directory/">link to the feed directory</a>.</p>
+</body>
+</html>
diff --git a/configs/index.html b/configs/index.html
deleted file mode 100644
index f5c8d9fd..00000000
--- a/configs/index.html
+++ /dev/null
@@ -1,133 +0,0 @@
----
-layout: default
-title: Ready-to-use configs
-noindex: true
-# nav_order: 1
----
-
-<noscript>
-  <span class="noscript">
-    This site needs JavaScript to link to the feed URL!
-  </span>
-</noscript>
-
-<div id="configs">
-  <fieldset class="mb-4 py-1 px-2">
-    <legend class="fs-5">Instance URL</legend>
-
-    <input
-      type="text"
-      name="instance"
-      value="https://1.h2r.workers.dev"
-      class="bg-grey-dk-100 p-2"
-    />
-  </fieldset>
-
-  <p class="fs-4">
-    Find publicly available instances in the
-    <a
-      href="https://github.com/html2rss/html2rss-web/wiki/Instances"
-      target="_blank"
-      >wiki</a
-    >
-    or
-    <a href="https://github.com/html2rss/html2rss-web" target="_blank"
-      >host your own</a
-    >.
-  </p>
-
-  {% for config in site.data.configs %}
-  <details class="py-1 px-2">
-    <summary class="config__headline text-mono">
-      <span>{{ config.domain }}</span><span class="text-yellow-300">/</span
-      ><span>{{ config.name }}</span>
-
-      {%- if config.valid_channel_url -%}
-      <a
-        href="#"
-        data-bind-click="show"
-        data-path="{{ config.domain }}/{{ config.name }}.rss"
-        class="float-right"
-        rel="noopener noreferrer"
-      >
-        RSS</a
-      >
-      {% endif %}
-    </summary>
-
-    <dl>
-      {%- if config.channel.url -%}
-      <dt>URL to scrape</dt>
-      <dd>
-        {%- if config.valid_channel_url -%}
-        <a
-          href="{{ config.channel.url }}"
-          class="config__url"
-          target="_blank"
-          rel="noopener noreferrer"
-          >{{ config.channel.url }}</a
-        >
-        {%- else -%}
-        <span class="config__url">{{ config.channel.url | xml_escape }}</span>
-        {%- endif -%}
-      </dd>
-      {%- endif -%} {%- if config.channel.time_zone -%}
-      <dt>Time zone</dt>
-      <dd>{{ config.channel.time_zone }}</dd>
-      {%- endif -%} {%- if config.channel.language -%}
-      <dt>Language</dt>
-      <dd>{{ config.channel.language }}</dd>
-      {%- endif -%}
-    </dl>
-
-    {%- if config.valid_channel_url -%}
-    <div>
-      <a
-        href="#"
-        data-bind-click="show"
-        data-path="{{ config.domain }}/{{ config.name }}.rss"
-        class="btn btn-primary fs-3 mb-4 mr-2 v-align-middle"
-        rel="noopener noreferrer"
-        >Show RSS</a
-      >
-
-      <button
-        data-bind-click="copy"
-        data-path="{{ config.domain }}/{{ config.name }}.rss"
-        class="btn fs-3 mb-4 mr-2 v-align-middle"
-        rel="noopener noreferrer"
-      >
-        Copy URL
-      </button>
-
-      <a
-        href="https://github.com/html2rss/html2rss-configs/blob/master/lib/html2rss/configs/{{ config.domain }}/{{ config.name }}.yml"
-        class="btn fs-3 mb-4 v-align-middle"
-      >
-        View on Github
-      </a>
-    </div>
-    {%- else -%}
-    <p class="bg-grey-dk-200 text-red-300 p-2">
-      This config requires parameters to work.<br />
-      <a
-        href="https://github.com/html2rss/html2rss-configs/blob/master/lib/html2rss/configs/{{ config.domain }}/{{ config.name }}.yml"
-        >View the config</a
-      >
-      to find out which values are possible.
-      <br />
-      <code class="d-block w-100 py-2 bg-grey-dk-300 text-grey-dk-000 fs-4">
-        <span class="config__url"
-          ><span class="instance"></span>{{ config.domain }}/{{ config.name
-          }}.rss?{% for params in config.url_parameters %}{{ params[0] }}=<em
-            >{{ params[1] }}</em
-          ><span class="config__url-amp">&</span>{% endfor %}
-        </span>
-      </code>
-    </p>
-    {%- endif -%}
-  </details>
-  {% endfor %}
-</div>
-
-<script src="/assets/js/configs/index.js" async defer></script>
diff --git a/feed-directory/index.html b/feed-directory/index.html
new file mode 100644
index 00000000..e286c561
--- /dev/null
+++ b/feed-directory/index.html
@@ -0,0 +1,228 @@
+---
+layout: default
+title: Feed Directory
+nav_order: 2
+noindex: true
+---
+
+<div class="text-center">
+  <h1 class="fs-9">Welcome to the Feed Directory!</h1>
+  <p class="fs-5">
+    This directory contains a list of pre-built configurations to create RSS
+    feeds for various websites.
+  </p>
+</div>
+
+<div class="mt-6">
+  <h2 class="fs-6">What is an Instance URL?</h2>
+  <p>
+    An "Instance URL" is the address of a running `html2rss-web` application.
+    You can use a publicly available instance or, for a more decentralized and
+    robust web, you can host your own.
+  </p>
+  <p>
+    By hosting your own instance, you contribute to the resilience of the
+    html2rss ecosystem and help keep the web open and accessible to everyone.
+  </p>
+  <a
+    href="{{ '/web-application/guides/deployment' | relative_url }}"
+    class="btn btn-primary"
+  >
+    🚀 Host Your Own Instance
+  </a>
+  <p class="mt-2">
+    Or, find a publicly available instance on the
+    <a
+      href="https://github.com/html2rss/html2rss-web/wiki/Instances"
+      target="_blank"
+      >community-run wiki</a
+    >.
+  </p>
+</div>
+
+<hr class="my-6" />
+
+{%- assign ob = '{' -%} {%- assign cb = '}' -%}
+
+<noscript>
+  <span class="noscript">
+    This site needs JavaScript to link to the feed URL!
+  </span>
+</noscript>
+
+<div id="configs">
+  <fieldset class="mb-4 py-1 px-2">
+    <legend class="fs-5">Instance URL</legend>
+
+    <input
+      type="text"
+      name="instance"
+      value="https://1.h2r.workers.dev"
+      class="bg-grey-dk-100 p-2"
+    />
+  </fieldset>
+
+  <fieldset class="mb-4 py-1 px-2">
+    <legend class="fs-5">Search</legend>
+
+    <input
+      type="search"
+      name="search"
+      placeholder="e.g. heise"
+      class="bg-grey-dk-100 p-2"
+    />
+  </fieldset>
+
+  <div class="card-deck">
+    {% for config in site.data.configs %}
+    <div class="card mb-4">
+      <div class="card-header d-flex-justify-content-between">
+        <h3 class="card-title mb-0 text-mono fs-5">
+          {{ config.domain }}/{{ config.name }}
+        </h3>
+        {%- if config.valid_channel_url -%}
+        <span class="badge text-green-000">Ready to use</span>
+        {%- else -%}
+        <span class="badge text-yellow-000">Requires parameters</span>
+        {%- endif -%}
+      </div>
+      <div class="card-body">
+        <details>
+          <summary>Details</summary>
+          <dl>
+            {%- if config.channel.url -%}
+            <dt>URL to scrape</dt>
+            <dd>
+              {%- if config.valid_channel_url -%}
+              <a
+                href="{{ config.channel.url }}"
+                class="config__url"
+                target="_blank"
+                rel="noopener noreferrer"
+                >{{ config.channel.url }}</a
+              >
+              {%- else -%}
+              <span class="config__url"
+                >{{ config.channel.url | xml_escape }}</span
+              >
+              {%- endif -%}
+            </dd>
+            {%- endif -%} {%- if config.channel.time_zone -%}
+            <dt>Time zone</dt>
+            <dd>{{ config.channel.time_zone }}</dd>
+            {%- endif -%} {%- if config.channel.language -%}
+            <dt>Language</dt>
+            <dd>{{ config.channel.language }}</dd>
+            {%- endif -%}
+          </dl>
+        </details>
+
+        {%- if config.valid_channel_url -%}
+        <div class="mt-4 d-flex-justify-content-between">
+          <a
+            href="#"
+            data-bind-click="show"
+            data-path="{{ config.domain }}/{{ config.name }}.rss"
+            class="btn btn-primary"
+            rel="noopener noreferrer"
+            >Show RSS</a
+          >
+          <button
+            data-bind-click="copy"
+            data-path="{{ config.domain }}/{{ config.name }}.rss"
+            class="btn btn-icon"
+            rel="noopener noreferrer"
+            title="Copy URL"
+          >
+            <svg><use xlink:href="#copy-icon"></use></svg>
+          </button>
+          <a
+            href="https://github.com/html2rss/html2rss-configs/blob/master/lib/html2rss/configs/{{ config.domain }}/{{ config.name }}.yml"
+            class="btn"
+            target="_blank"
+          >
+            View YAML
+          </a>
+        </div>
+        {%- else -%}
+        <div class="mt-4" data-dynamic-form>
+          <form>
+            {% for param in config.url_parameters %}
+            <div class="form-group">
+              <label for="{{ config.domain }}-{{ config.name }}-{{ param[0] }}"
+                >{{ param[0] }}</label
+              >
+              <input
+                type="text"
+                id="{{ config.domain }}-{{ config.name }}-{{ param[0] }}"
+                name="{{ param[0] }}"
+                class="form-control"
+                placeholder="{{ param[1] }}"
+                data-param
+              />
+            </div>
+            {% endfor %}
+          </form>
+          <div class="mt-2 d-flex-justify-content-between">
+            <a
+              href="#"
+              data-bind-click="show"
+              data-path-template="{{ config.domain }}/{{ config.name }}.rss?{% for param in config.url_parameters %}{{ param[0] }}={{ ob }}{{ param[0] }}{{ cb }}&{% endfor %}"
+              class="btn btn-primary"
+              rel="noopener noreferrer"
+              >Show RSS</a
+            >
+            <button
+              data-bind-click="copy"
+              data-path-template="{{ config.domain }}/{{ config.name }}.rss?{% for param in config.url_parameters %}{{ param[0] }}={{ ob }}{{ param[0] }}{{ cb }}&{% endfor %}"
+              class="btn btn-icon"
+              rel="noopener noreferrer"
+              title="Copy URL"
+            >
+              <svg><use xlink:href="#copy-icon"></use></svg>
+            </button>
+            <a
+              href="https://github.com/html2rss/html2rss-configs/blob/master/lib/html2rss/configs/{{ config.domain }}/{{ config.name }}.yml"
+              class="btn"
+              target="_blank"
+            >
+              View YAML
+            </a>
+          </div>
+          <div class="mt-2">
+            <code class="d-block w-100 p-2 bg-grey-dk-300 text-grey-dk-000">
+              <span class="instance"></span
+              ><span data-path-preview
+                >{{ config.domain }}/{{ config.name }}.rss?{% for param in
+                config.url_parameters %}{{ param[0] }}={{ ob }}{{ param[1] }}{{
+                cb }}&{% endfor %}</span
+              >
+            </code>
+          </div>
+        </div>
+        {%- endif -%}
+      </div>
+    </div>
+    {% endfor %}
+  </div>
+</div>
+
+<hr class="my-6" />
+
+<div class="text-center">
+  <h2 class="fs-6">Contribute to the Directory</h2>
+  <p class="fs-5">
+    The feed configurations in this directory are community-driven. If you've
+    created a new feed configuration, we encourage you to share it with the
+    community.
+  </p>
+  <a
+    href="https://github.com/html2rss/html2rss-configs"
+    class="btn btn-primary"
+    target="_blank"
+  >
+    Contribute on GitHub
+  </a>
+</div>
+
+<script src="/assets/js/feed-directory/index.js" async defer></script>
diff --git a/web-application/contributing/index.md b/web-application/contributing/index.md
deleted file mode 100644
index 391291e8..00000000
--- a/web-application/contributing/index.md
+++ /dev/null
@@ -1,15 +0,0 @@
----
-layout: default
-title: Contributing
-nav_order: 4
-permalink: /web-application/contributing
-parent: Web Application
----
-
-# Contributing
-
-Contributions are welcome!
-
-Open a pull request with your changes,
-open an issue, or
-[join discussions on html2rss](https://github.com/orgs/html2rss/discussions).
diff --git a/web-application/index.md b/web-application/index.md
index f141d301..29adc171 100644
--- a/web-application/index.md
+++ b/web-application/index.md
@@ -14,7 +14,7 @@ This web application scrapes websites to build and deliver RSS 2.0 feeds.
 
 - **Stable URLs:** Provides stable URLs for feeds generated by automatic sourcing.
 - **Custom Feeds:** Create your own custom feeds.
-- **Included Configs:** Comes with plenty of [included configs](https://github.com/html2rss/html2rss-configs) out of the box.
+- **Feed Directory:** Comes with plenty of [feeds](https://github.com/html2rss/html2rss-configs) out of the box.
 - **Caching:** Handles request caching and sets caching-related HTTP headers.
 
 The functionality of scraping websites and building the RSS feeds is provided by the Ruby gem [`html2rss`](https://github.com/html2rss/html2rss).
diff --git a/web-application/reference/included-configs.md b/web-application/reference/included-configs.md
deleted file mode 100644
index 04e9d951..00000000
--- a/web-application/reference/included-configs.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-layout: default
-title: Included Configs
-nav_order: 2
-permalink: /web-application/reference/included-configs
-parent: Reference
-grand_parent: Web Application
----
-
-# Included Configs
-
-html2rss-web comes with many feed configs out of the box. [See the file list of all configs.](https://github.com/html2rss/html2rss-configs/tree/master/lib/html2rss/configs)
-
-To use a config from there, build the URL like this:
-
-|                          |                               |
-| ------------------------ | ----------------------------- |
-| `lib/html2rss/configs/`  | `domainname.tld/whatever.yml` |
-| Would become this URL:   |                               |
-| `http://localhost:3000/` | `domainname.tld/whatever.rss` |
-|                          | `^^^^^^^^^^^^^^^^^^^^^^^^^^^` |

From a6112bc7bf3eb8740b99494647743505339eb56c Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 26 Jul 2025 16:38:03 +0200
Subject: [PATCH 07/17] refactor: reorganize documentation structure and update
 permalinks

---
 about.md                                      | 30 +++++----------
 .../contributing.md                           | 11 +++++-
 get-involved/discussions.md                   | 15 ++++++++
 get-involved/index.md                         | 21 ++++++++++
 get-involved/issues-and-features.md           | 38 +++++++++++++++++++
 index.md                                      | 25 +++++-------
 ruby-gem/configuration/index.md               | 25 ------------
 .../advanced-content-extraction.md            | 10 ++---
 .../how-to}/creating-custom-feeds.md          |  6 +--
 .../custom-http-requests.md                   |  8 ++--
 .../dynamic-parameters.md                     |  6 +--
 .../handling-dynamic-content.md               |  8 ++--
 ruby-gem/{examples => how-to}/index.md        |  8 ++--
 .../{examples => how-to}/simple-blog-list.md  |  6 +--
 .../{examples => how-to}/styling-rss-feed.md  |  8 ++--
 ruby-gem/index.md                             |  5 ++-
 .../auto_source.md                            |  6 +--
 .../{configuration => reference}/channel.md   |  6 +--
 .../reference/cli-reference.md                |  9 +++--
 .../{configuration => reference}/headers.md   |  8 ++--
 ruby-gem/reference/index.md                   | 24 ++++++++++++
 .../index.md => reference/selectors.md}       | 14 +++----
 .../selectors/extractors.md                   |  3 +-
 .../selectors/post-processors.md              |  3 +-
 .../{configuration => reference}/strategy.md  |  6 +--
 .../stylesheets.md                            |  4 +-
 ruby-gem/{ => tutorials}/getting-started.md   | 10 ++---
 ruby-gem/{ => tutorials}/installation.md      |  6 +--
 ruby-gem/{ => tutorials}/your-first-feed.md   |  4 +-
 support/contact.md                            | 36 ------------------
 web-application/guides/deployment.md          | 32 ----------------
 .../{guides => how-to}/automatic-updates.md   |  6 +--
 web-application/how-to/deployment.md          | 23 +++++++++++
 web-application/{guides => how-to}/index.md   |  6 +--
 .../{guides => how-to}/monitoring.md          |  4 +-
 web-application/index.md                      | 11 ++++++
 .../{configuration.md => env-variables.md}    |  3 +-
 .../{getting-started => tutorials}/index.md   | 10 ++---
 38 files changed, 248 insertions(+), 216 deletions(-)
 rename contributing.md => get-involved/contributing.md (86%)
 create mode 100644 get-involved/discussions.md
 create mode 100644 get-involved/index.md
 create mode 100644 get-involved/issues-and-features.md
 delete mode 100644 ruby-gem/configuration/index.md
 rename ruby-gem/{examples => how-to}/advanced-content-extraction.md (59%)
 rename {web-application/guides => ruby-gem/how-to}/creating-custom-feeds.md (84%)
 rename ruby-gem/{examples => how-to}/custom-http-requests.md (55%)
 rename ruby-gem/{examples => how-to}/dynamic-parameters.md (92%)
 rename ruby-gem/{examples => how-to}/handling-dynamic-content.md (52%)
 rename ruby-gem/{examples => how-to}/index.md (90%)
 rename ruby-gem/{examples => how-to}/simple-blog-list.md (96%)
 rename ruby-gem/{examples => how-to}/styling-rss-feed.md (51%)
 rename ruby-gem/{configuration => reference}/auto_source.md (96%)
 rename ruby-gem/{configuration => reference}/channel.md (96%)
 rename api-reference.md => ruby-gem/reference/cli-reference.md (89%)
 rename ruby-gem/{configuration => reference}/headers.md (88%)
 create mode 100644 ruby-gem/reference/index.md
 rename ruby-gem/{configuration/selectors/index.md => reference/selectors.md} (91%)
 rename ruby-gem/{configuration => reference}/selectors/extractors.md (93%)
 rename ruby-gem/{configuration => reference}/selectors/post-processors.md (94%)
 rename ruby-gem/{configuration => reference}/strategy.md (97%)
 rename ruby-gem/{configuration => reference}/stylesheets.md (95%)
 rename ruby-gem/{ => tutorials}/getting-started.md (87%)
 rename ruby-gem/{ => tutorials}/installation.md (94%)
 rename ruby-gem/{ => tutorials}/your-first-feed.md (96%)
 delete mode 100644 support/contact.md
 delete mode 100644 web-application/guides/deployment.md
 rename web-application/{guides => how-to}/automatic-updates.md (73%)
 create mode 100644 web-application/how-to/deployment.md
 rename web-application/{guides => how-to}/index.md (70%)
 rename web-application/{guides => how-to}/monitoring.md (94%)
 rename web-application/reference/{configuration.md => env-variables.md} (95%)
 rename web-application/{getting-started => tutorials}/index.md (90%)

diff --git a/about.md b/about.md
index c0ca94b8..24ba6587 100644
--- a/about.md
+++ b/about.md
@@ -1,39 +1,29 @@
 ---
 layout: default
 title: About html2rss
-# nav_order: 2
+nav_order: 2
 ---
 
 # About html2rss
 
-`html2rss` is an open-source project dedicated to empowering users to take control of their web content consumption. In an age where many websites no longer offer traditional RSS feeds, `html2rss` bridges this gap by providing a robust and flexible solution for converting any HTML content into a structured RSS format.
+`html2rss` is an open-source project dedicated to empowering you to take control of your web content. In an age where traditional RSS feeds are often missing, `html2rss` provides a robust and flexible solution to convert almost any HTML content into a structured RSS format.
 
-The project was started in 2018 and has since grown into a suite of tools that help users create and consume RSS feeds.
+Started in 2018, the project has evolved into a comprehensive suite of tools designed to help you create and consume RSS feeds effortlessly.
 
 ---
 
-### Our Mission
+## Our Vision and Principles
 
 Our mission is to provide a simple, powerful, and accessible tool that enables individuals and developers to create custom RSS feeds from any web page. We believe in the power of open standards and the freedom to access information on your own terms.
 
----
-
-### The html2rss Ecosystem
-
-The `html2rss` project is more than just a single tool. It's a collection of tools that work together to provide a complete RSS solution:
-
-- **[`html2rss`](https://github.com/html2rss/html2rss):** The core Ruby gem that provides the main functionality for converting HTML to RSS.
-- **[`html2rss-web`](https://github.com/html2rss/html2rss-web):** A web application that allows you to create and manage your RSS feeds through a user-friendly interface.
-- **[`html2rss-configs`](https://github.com/html2rss/html2rss-configs):** A collection of pre-built feed configs for popular websites, so you can get started quickly.
-
----
+Our project is guided by these core principles:
 
-### Project Philosophy
+- **User Empowerment:** Giving you the tools to customize your web experience.
+- **Simplicity & Power:** Offering an easy-to-use interface with powerful underlying capabilities.
+- **Open Source:** Fostering a collaborative environment where the community can contribute and improve the project.
+- **Reliability:** Striving for a stable and dependable tool that consistently delivers.
 
-- **User Empowerment:** Give users the tools to customize their web experience.
-- **Simplicity & Power:** Offer an easy-to-use interface with powerful underlying capabilities.
-- **Open Source:** Foster a collaborative environment where the community can contribute and improve the project.
-- **Reliability:** Strive for a stable and dependable tool that consistently delivers.
+For insights into our ongoing development, project roadmap, and how you can get involved, please visit our [Get Involved]({{ '/get-involved' | relative_url }}) page.
 
 ---
 
diff --git a/contributing.md b/get-involved/contributing.md
similarity index 86%
rename from contributing.md
rename to get-involved/contributing.md
index df88d159..40cb43e1 100644
--- a/contributing.md
+++ b/get-involved/contributing.md
@@ -1,6 +1,7 @@
 ---
 layout: default
 title: Contributing
+parent: Get Involved
 nav_order: 10
 ---
 
@@ -44,14 +45,20 @@ Are you a Ruby developer? You can help us improve the core `html2rss` gem. Wheth
 
 [**Check out the repository on GitHub**](https://github.com/html2rss/html2rss)
 
-### 5. Report Bugs and Request Features
+### 5. Report Bugs & Discuss Features
 
-If you've found a bug or have an idea for a new feature, please let us know! You can open an issue on the appropriate GitHub repository.
+If you've found a bug, please open an issue on the appropriate GitHub repository. For new feature ideas, we encourage you to start a discussion first.
+
+**Report Bugs:**
 
 - [**`html2rss` issues**](https://github.com/html2rss/html2rss/issues)
 - [**`html2rss-web` issues**](https://github.com/html2rss/html2rss-web/issues)
 - [**`html2rss-configs` issues**](https://github.com/html2rss/html2rss-configs/issues)
 
+**Discuss Features:**
+
+- [**Start a New Discussion on GitHub**](https://github.com/orgs/html2rss/discussions)
+
 ---
 
 We appreciate your interest in contributing to `html2rss`!
diff --git a/get-involved/discussions.md b/get-involved/discussions.md
new file mode 100644
index 00000000..54740a0b
--- /dev/null
+++ b/get-involved/discussions.md
@@ -0,0 +1,15 @@
+---
+layout: default
+title: Join Community Discussions
+nav_order: 2
+parent: Get Involved
+permalink: /get-involved/discussions
+---
+
+# Join Community Discussions
+
+Connect with other users and contributors by joining our community discussions on GitHub. This is a vibrant space for general questions, sharing tips, discussing ideas, and getting feedback from the community.
+
+[**💬 Join Discussions on GitHub**](https://github.com/orgs/html2rss/discussions)
+
+We encourage you to participate, ask questions, and share your insights!
diff --git a/get-involved/index.md b/get-involved/index.md
new file mode 100644
index 00000000..d26c871c
--- /dev/null
+++ b/get-involved/index.md
@@ -0,0 +1,21 @@
+---
+layout: default
+title: Get Involved
+has_children: true
+nav_order: 4
+---
+
+# Get Involved
+
+Want to participate in the `html2rss` project? Explore the options below to engage with our community and contribute to the project's growth.
+
+---
+
+- [**Report Bugs & Discuss Features**]({{ '/get-involved/issues-and-features' | relative_url }}): Found a bug or have a new feature idea? Learn where to report and discuss them.
+- [**Join Community Discussions**]({{ '/get-involved/discussions' | relative_url }}): Connect with other users and contributors, ask questions, and share ideas.
+- [**Contribute to html2rss**]({{ '/contributing' | relative_url }}): Ready to contribute code, documentation, or feed configurations? Find detailed guides here.
+- [**📊 View Project Roadmap & Tasks**]({{ 'https://github.com/orgs/html2rss/projects/3/views/1' }}): See what's being worked on, planned, and needs attention across all `html2rss` projects.
+
+---
+
+We appreciate your interest in `html2rss` and look forward to your involvement!
diff --git a/get-involved/issues-and-features.md b/get-involved/issues-and-features.md
new file mode 100644
index 00000000..3fb0bfa0
--- /dev/null
+++ b/get-involved/issues-and-features.md
@@ -0,0 +1,38 @@
+---
+layout: default
+title: Report Bugs & Discuss Features
+nav_order: 1
+parent: Get Involved
+permalink: /get-involved/issues-and-features
+---
+
+# Report Bugs & Discuss Features
+
+We appreciate your help in improving `html2rss`! Please follow these guidelines when reporting issues or suggesting new features.
+
+---
+
+### Reporting Bugs
+
+If you've found a bug, please open an issue on the appropriate GitHub repository. This helps us track and resolve problems efficiently.
+
+[**➡️ Open an Issue on GitHub**](https://github.com/html2rss/html2rss/issues)
+
+When opening a bug report, please provide as much detail as possible, including:
+
+- The `html2rss` version you are using.
+- Your operating system.
+- Your configuration file (if applicable).
+- The target URL you are trying to scrape.
+- Any error messages you receive.
+- Steps to reproduce the issue.
+
+---
+
+### Discussing New Features
+
+For new feature ideas or enhancements, we encourage you to start a discussion on GitHub Discussions first. This allows for community input, refinement of the idea, and helps us prioritize development.
+
+[**💬 Start a New Discussion on GitHub**](https://github.com/orgs/html2rss/discussions)
+
+If the discussion leads to a concrete proposal, a formal feature request issue can then be opened.
diff --git a/index.md b/index.md
index 60105d55..f4d7f28b 100644
--- a/index.md
+++ b/index.md
@@ -12,19 +12,8 @@ Tired of missing updates from websites that don't offer RSS feeds? `html2rss` is
 
 ---
 
-## The html2rss Ecosystem
-
-`html2rss` is a suite of tools designed to help you create and manage RSS feeds.
-
-- **[html2rss-web]({{ '/web-application' | relative_url }}):** A user-friendly web application that makes it easy to create, manage, and share RSS feeds. This is the recommended starting point for most users.
-- **[html2rss (Ruby Gem)]({{ '/ruby-gem' | relative_url }}):** The core library that powers the web application. It provides a powerful and flexible command-line interface for creating custom RSS feeds.
-- **[html2rss-configs](https://github.com/html2rss/html2rss-configs):** A community-driven repository of pre-built feed configurations for popular websites.
-
----
-
 ## Key Features
 
-- **User-Friendly Web Interface:** The `html2rss-web` application provides a simple and intuitive interface for managing your feeds.
 - **Automatic Feed Generation:** The `auto_source` scraper intelligently finds and extracts content from websites, so you can create feeds with minimal effort.
 - **Precise Content Extraction:** Use familiar CSS selectors to target the exact content you want to include in your feed.
 - **JavaScript Rendering:** Use a headless browser to render JavaScript-heavy websites and extract content that isn't available in the initial HTML.
@@ -32,10 +21,14 @@ Tired of missing updates from websites that don't offer RSS feeds? `html2rss` is
 
 ---
 
-### Join the Community
+## The html2rss Ecosystem
+
+The `html2rss` project is more than just a single tool. It's a collection of tools that work together to provide a complete RSS solution:
 
-Have a question, an idea, or a success story to share? Join the `html2rss` community on GitHub!
+- **[html2rss-web]({{ '/web-application' | relative_url }}):** A user-friendly web application that makes it easy to create, manage, and share RSS feeds. This is the recommended starting point for most users.
+- **[html2rss (Ruby Gem)]({{ '/ruby-gem' | relative_url }}):** The core library that powers the web application. It provides a powerful and flexible command-line interface for creating custom RSS feeds.
+- **[html2rss-configs](https://github.com/html2rss/html2rss-configs):** A community-driven repository of pre-built feed configurations for popular websites, so you can get started quickly.
+
+---
 
-- **[Discussions](https://github.com/orgs/html2rss/discussions):** Ask questions, share ideas, and connect with other users.
-- **[Issues](https://github.com/html2rss/html2rss/issues):** Report bugs and request new features.
-- **[Contribute](https://github.com/html2rss/html2rss/fork):** Fork the repository and submit your own improvements.
+Want to engage with the `html2rss` community or contribute to the project? Visit our [Get Involved]({{ '/get-involved' | relative_url }}) page for details on discussions, reporting issues, and contributing.
diff --git a/ruby-gem/configuration/index.md b/ruby-gem/configuration/index.md
deleted file mode 100644
index c16b66c0..00000000
--- a/ruby-gem/configuration/index.md
+++ /dev/null
@@ -1,25 +0,0 @@
----
-layout: default
-title: Configuration
-nav_order: 4
-parent: Ruby Gem
-has_children: true
-permalink: /ruby-gem/configuration
----
-
-# Configuration
-
-While the `html2rss auto` command is a great starting point, you'll often need to create a YAML configuration file to get the perfect RSS feed. A configuration file gives you fine-grained control over every aspect of the feed generation process.
-
-This section provides a comprehensive guide to all the configuration options available in `html2rss`.
-
-## Configuration Topics
-
-- [**Auto Source**]({{ '/ruby-gem/configuration/auto_source' | relative_url }}): The easiest way to create a feed, with minimal configuration.
-- [**Channel**]({{ '/ruby-gem/configuration/channel' | relative_url }}): Customize the metadata of your RSS feed.
-- [**Selectors**]({{ '/ruby-gem/configuration/selectors' | relative_url }}): Use CSS selectors to extract content with precision.
-- [**Extractors**]({{ '/ruby-gem/configuration/selectors/extractors' | relative_url }}): Specify how to extract information from HTML elements.
-- [**Post Processors**]({{ '/ruby-gem/configuration/selectors/post-processors' | relative_url }}): Manipulate the extracted data to get it just right.
-- [**Strategy**]({{ '/ruby-gem/configuration/strategy' | relative_url }}): Define how html2rss fetches website content, including JavaScript rendering options.
-- [**Headers**]({{ '/ruby-gem/configuration/headers' | relative_url }}): Set custom HTTP headers for requests, useful for APIs and authorization.
-- [**Stylesheets**]({{ '/ruby-gem/configuration/stylesheets' | relative_url }}): Add CSS or XSLT stylesheets to style your RSS feed in browsers.
diff --git a/ruby-gem/examples/advanced-content-extraction.md b/ruby-gem/how-to/advanced-content-extraction.md
similarity index 59%
rename from ruby-gem/examples/advanced-content-extraction.md
rename to ruby-gem/how-to/advanced-content-extraction.md
index 2ae23990..5ad14155 100644
--- a/ruby-gem/examples/advanced-content-extraction.md
+++ b/ruby-gem/how-to/advanced-content-extraction.md
@@ -1,10 +1,10 @@
 ---
 layout: default
 title: Advanced Content Extraction
-nav_order: 1
-parent: Examples
+nav_order: 3
+parent: How-To Guides
 grand_parent: Ruby Gem
-permalink: /ruby-gem/examples/advanced-content-extraction
+permalink: /ruby-gem/how-to/advanced-content-extraction
 ---
 
 # Advanced Content Extraction with Selectors
@@ -13,8 +13,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/configuration/selectors/extractors' | relative_url }}).
+Learn how to extract specific attributes (like `src` for images) or static values. See [Extractors]({{ '/ruby-gem/reference/selectors/extractors' | relative_url }}).
 
 ## Post Processors
 
-Manipulate extracted text, sanitize HTML, convert Markdown, or apply custom logic. See [Post Processors]({{ '/ruby-gem/configuration/selectors/post-processors' | relative_url }}).
+Manipulate extracted text, sanitize HTML, convert Markdown, or apply custom logic. See [Post Processors]({{ '/ruby-gem/reference/selectors/post-processors' | relative_url }}).
diff --git a/web-application/guides/creating-custom-feeds.md b/ruby-gem/how-to/creating-custom-feeds.md
similarity index 84%
rename from web-application/guides/creating-custom-feeds.md
rename to ruby-gem/how-to/creating-custom-feeds.md
index 586eccde..b7d3057e 100644
--- a/web-application/guides/creating-custom-feeds.md
+++ b/ruby-gem/how-to/creating-custom-feeds.md
@@ -2,9 +2,9 @@
 layout: default
 title: Creating Custom Feeds
 nav_order: 1
-permalink: /web-application/guides/creating-custom-feeds
-parent: Guides
-grand_parent: Web Application
+permalink: /web-application/how-to/creating-custom-feeds
+parent: How-To Guides
+grand_parent: Ruby Gem
 ---
 
 # Creating Your First Custom Feed
diff --git a/ruby-gem/examples/custom-http-requests.md b/ruby-gem/how-to/custom-http-requests.md
similarity index 55%
rename from ruby-gem/examples/custom-http-requests.md
rename to ruby-gem/how-to/custom-http-requests.md
index cd8506f5..8dc26881 100644
--- a/ruby-gem/examples/custom-http-requests.md
+++ b/ruby-gem/how-to/custom-http-requests.md
@@ -1,10 +1,10 @@
 ---
 layout: default
 title: Custom HTTP Requests
-nav_order: 2
-parent: Examples
+nav_order: 4
+parent: How-To Guides
 grand_parent: Ruby Gem
-permalink: /ruby-gem/examples/custom-http-requests
+permalink: /ruby-gem/how-to/custom-http-requests
 ---
 
 # Customizing HTTP Requests
@@ -13,4 +13,4 @@ You might need to send custom HTTP headers (e.g., `User-Agent`, `Authorization`)
 
 ## Solution
 
-Configure [custom HTTP headers]({{ '/ruby-gem/configuration/headers' | relative_url }}) in your feed configuration.
+Configure [custom HTTP headers]({{ '/ruby-gem/reference/headers' | relative_url }}) in your feed configuration.
diff --git a/ruby-gem/examples/dynamic-parameters.md b/ruby-gem/how-to/dynamic-parameters.md
similarity index 92%
rename from ruby-gem/examples/dynamic-parameters.md
rename to ruby-gem/how-to/dynamic-parameters.md
index 801d14e8..6f83836e 100644
--- a/ruby-gem/examples/dynamic-parameters.md
+++ b/ruby-gem/how-to/dynamic-parameters.md
@@ -1,10 +1,10 @@
 ---
 layout: default
 title: Dynamic Parameters
-nav_order: 3
-parent: Examples
+nav_order: 5
+parent: How-To Guides
 grand_parent: Ruby Gem
-permalink: /ruby-gem/examples/dynamic-parameters
+permalink: /ruby-gem/how-to/dynamic-parameters
 ---
 
 # Dynamic Parameters in URLs and Headers
diff --git a/ruby-gem/examples/handling-dynamic-content.md b/ruby-gem/how-to/handling-dynamic-content.md
similarity index 52%
rename from ruby-gem/examples/handling-dynamic-content.md
rename to ruby-gem/how-to/handling-dynamic-content.md
index 69cece6f..c25ddcb2 100644
--- a/ruby-gem/examples/handling-dynamic-content.md
+++ b/ruby-gem/how-to/handling-dynamic-content.md
@@ -1,10 +1,10 @@
 ---
 layout: default
 title: Handling Dynamic Content
-nav_order: 4
-parent: Examples
+nav_order: 6
+parent: How-To Guides
 grand_parent: Ruby Gem
-permalink: /ruby-gem/examples/handling-dynamic-content
+permalink: /ruby-gem/how-to/handling-dynamic-content
 ---
 
 # Handling Dynamic Content and JavaScript
@@ -13,4 +13,4 @@ Some websites load their content dynamically using JavaScript. The default `html
 
 ## Solution
 
-Use the [`browserless` strategy]({{ '/ruby-gem/configuration/strategy' | relative_url }}) to render JavaScript-heavy websites with a headless browser.
+Use the [`browserless` strategy]({{ '/ruby-gem/reference/strategy' | relative_url }}) to render JavaScript-heavy websites with a headless browser.
diff --git a/ruby-gem/examples/index.md b/ruby-gem/how-to/index.md
similarity index 90%
rename from ruby-gem/examples/index.md
rename to ruby-gem/how-to/index.md
index 874eea65..2d312a27 100644
--- a/ruby-gem/examples/index.md
+++ b/ruby-gem/how-to/index.md
@@ -1,13 +1,13 @@
 ---
 layout: default
-title: Examples
-nav_order: 5
+title: How-To Guides
+nav_order: 3
 parent: Ruby Gem
 has_children: true
-permalink: /ruby-gem/examples
+permalink: /ruby-gem/how-to
 ---
 
-# Examples: Practical `html2rss` Configurations
+# How-To Guides: Practical `html2rss` Configurations
 
 This section provides a collection of ready-to-use `html2rss` configuration examples for various popular websites and common use cases. These examples demonstrate how to tackle different HTML structures and content types.
 
diff --git a/ruby-gem/examples/simple-blog-list.md b/ruby-gem/how-to/simple-blog-list.md
similarity index 96%
rename from ruby-gem/examples/simple-blog-list.md
rename to ruby-gem/how-to/simple-blog-list.md
index 22c16451..153853d0 100644
--- a/ruby-gem/examples/simple-blog-list.md
+++ b/ruby-gem/how-to/simple-blog-list.md
@@ -1,10 +1,10 @@
 ---
 layout: default
 title: Simple Blog List
-nav_order: 5
-parent: Examples
+nav_order: 2
+parent: How-To Guides
 grand_parent: Ruby Gem
-permalink: /ruby-gem/examples/simple-blog-list
+permalink: /ruby-gem/how-to/simple-blog-list
 ---
 
 # Example: Scraping a Simple Blog List
diff --git a/ruby-gem/examples/styling-rss-feed.md b/ruby-gem/how-to/styling-rss-feed.md
similarity index 51%
rename from ruby-gem/examples/styling-rss-feed.md
rename to ruby-gem/how-to/styling-rss-feed.md
index ded55e9f..a290ffc9 100644
--- a/ruby-gem/examples/styling-rss-feed.md
+++ b/ruby-gem/how-to/styling-rss-feed.md
@@ -1,10 +1,10 @@
 ---
 layout: default
 title: Styling Your RSS Feed
-nav_order: 6
-parent: Examples
+nav_order: 7
+parent: How-To Guides
 grand_parent: Ruby Gem
-permalink: /ruby-gem/examples/styling-rss-feed
+permalink: /ruby-gem/how-to/styling-rss-feed
 ---
 
 # Styling Your RSS Feed
@@ -13,4 +13,4 @@ You can make your RSS feed look good in a web browser by attaching stylesheets.
 
 ## Solution
 
-Add [stylesheets]({{ '/ruby-gem/configuration/stylesheets' | relative_url }}) to your feed configuration.
+Add [stylesheets]({{ '/ruby-gem/reference/stylesheets' | relative_url }}) to your feed configuration.
diff --git a/ruby-gem/index.md b/ruby-gem/index.md
index 358e30fc..6a2ff54c 100644
--- a/ruby-gem/index.md
+++ b/ruby-gem/index.md
@@ -6,7 +6,7 @@ has_children: true
 permalink: /ruby-gem
 ---
 
-# For Developers: The html2rss Ruby Gem
+# The html2rss Ruby Gem
 
 This section provides detailed documentation for the `html2rss` Ruby gem. The gem is the core library that powers the `html2rss-web` application.
 
@@ -14,6 +14,9 @@ If you are looking for the easiest way to get started with `html2rss`, we recomm
 
 This documentation is for developers who want to:
 
+- Learn how to get started with the gem: [Tutorials]({{ '/ruby-gem/tutorials' | relative_url }})
+- Find solutions to common problems: [How-To Guides]({{ '/ruby-gem/how-to' | relative_url }})
+- Look up technical details and configuration options: [Reference]({{ '/ruby-gem/reference' | relative_url }})
 - Use the `html2rss` gem directly from the command line.
 - Integrate the `html2rss` gem into their own Ruby applications.
 - Contribute to the development of `html2rss`.
diff --git a/ruby-gem/configuration/auto_source.md b/ruby-gem/reference/auto_source.md
similarity index 96%
rename from ruby-gem/configuration/auto_source.md
rename to ruby-gem/reference/auto_source.md
index b6440448..8907908a 100644
--- a/ruby-gem/configuration/auto_source.md
+++ b/ruby-gem/reference/auto_source.md
@@ -1,10 +1,10 @@
 ---
 layout: default
 title: Auto Source
-nav_order: 1
-parent: Configuration
+nav_order: 5
+parent: Reference
 grand_parent: Ruby Gem
-permalink: /ruby-gem/configuration/auto_source
+permalink: /ruby-gem/reference/auto_source
 ---
 
 # `auto_source`
diff --git a/ruby-gem/configuration/channel.md b/ruby-gem/reference/channel.md
similarity index 96%
rename from ruby-gem/configuration/channel.md
rename to ruby-gem/reference/channel.md
index 25122c50..3ffd529d 100644
--- a/ruby-gem/configuration/channel.md
+++ b/ruby-gem/reference/channel.md
@@ -1,10 +1,10 @@
 ---
 layout: default
 title: Channel
-nav_order: 2
-parent: Configuration
+nav_order: 1
+parent: Reference
 grand_parent: Ruby Gem
-permalink: /ruby-gem/configuration/channel
+permalink: /ruby-gem/reference/channel
 ---
 
 # `channel`
diff --git a/api-reference.md b/ruby-gem/reference/cli-reference.md
similarity index 89%
rename from api-reference.md
rename to ruby-gem/reference/cli-reference.md
index fc0a4c93..9a0478c0 100644
--- a/api-reference.md
+++ b/ruby-gem/reference/cli-reference.md
@@ -1,10 +1,13 @@
 ---
 layout: default
-title: API Reference
-nav_order: 8
+title: CLI Reference
+nav_order: 7
+parent: Reference
+grand_parent: Ruby Gem
+permalink: /ruby-gem/reference/cli-reference
 ---
 
-# API Reference
+# CLI Reference
 
 This section provides a reference for the `html2rss` command-line interface (CLI).
 
diff --git a/ruby-gem/configuration/headers.md b/ruby-gem/reference/headers.md
similarity index 88%
rename from ruby-gem/configuration/headers.md
rename to ruby-gem/reference/headers.md
index f086717c..5572f271 100644
--- a/ruby-gem/configuration/headers.md
+++ b/ruby-gem/reference/headers.md
@@ -1,10 +1,10 @@
 ---
 layout: default
 title: Headers
-nav_order: 3
-parent: Configuration
+nav_order: 6
+parent: Reference
 grand_parent: Ruby Gem
-permalink: /ruby-gem/configuration/headers
+permalink: /ruby-gem/reference/headers
 ---
 
 # `headers`
@@ -19,7 +19,7 @@ headers:
 
 You can also set headers for APIs that require authorization or custom headers.
 
-Dynamic parameters can be used in headers to pass values at runtime. See [Dynamic Parameters]({{ '/ruby-gem/examples/dynamic-parameters' | relative_url }}) for more details.
+Dynamic parameters can be used in headers to pass values at runtime. See [Dynamic Parameters]({{ '/ruby-gem/how-to/dynamic-parameters' | relative_url }}) for more details.
 
 ## Example Configuration
 
diff --git a/ruby-gem/reference/index.md b/ruby-gem/reference/index.md
new file mode 100644
index 00000000..aa4fd456
--- /dev/null
+++ b/ruby-gem/reference/index.md
@@ -0,0 +1,24 @@
+---
+layout: default
+title: Reference
+nav_order: 4
+parent: Ruby Gem
+has_children: true
+---
+
+# Reference
+
+While the `html2rss auto` command is a great starting point, you'll often need to create a YAML configuration file to get the perfect RSS feed. A configuration file gives you fine-grained control over every aspect of the feed generation process.
+
+This section provides a comprehensive guide to all the configuration options available in `html2rss`.
+
+## Configuration Topics
+
+- [**Auto Source**]({{ '/ruby-gem/reference/auto_source' | relative_url }}): The easiest way to create a feed, with minimal configuration.
+- [**Channel**]({{ '/ruby-gem/reference/channel' | relative_url }}): Customize the metadata of your RSS feed.
+- [**Selectors**]({{ '/ruby-gem/reference/selectors' | relative_url }}): Use CSS selectors to extract content with precision.
+- [**Extractors**]({{ '/ruby-gem/reference/selectors/extractors' | relative_url }}): Specify how to extract information from HTML elements.
+- [**Post Processors**]({{ '/ruby-gem/reference/selectors/post-processors' | relative_url }}): Manipulate the extracted data to get it just right.
+- [**Strategy**]({{ '/ruby-gem/reference/strategy' | relative_url }}): Define how html2rss fetches website content, including JavaScript rendering options.
+- [**Headers**]({{ '/ruby-gem/reference/headers' | relative_url }}): Set custom HTTP headers for requests, useful for APIs and authorization.
+- [**Stylesheets**]({{ '/ruby-gem/reference/stylesheets' | relative_url }}): Add CSS or XSLT stylesheets to style your RSS feed in browsers.
diff --git a/ruby-gem/configuration/selectors/index.md b/ruby-gem/reference/selectors.md
similarity index 91%
rename from ruby-gem/configuration/selectors/index.md
rename to ruby-gem/reference/selectors.md
index 9fcf573b..3fa2fa4b 100644
--- a/ruby-gem/configuration/selectors/index.md
+++ b/ruby-gem/reference/selectors.md
@@ -2,10 +2,10 @@
 layout: default
 title: Selectors
 nav_order: 6
-parent: Configuration
+parent: Reference
 grand_parent: Ruby Gem
 has_children: true
-permalink: /ruby-gem/configuration/selectors
+permalink: /ruby-gem/reference/selectors
 ---
 
 # `selectors`
@@ -65,11 +65,11 @@ The following selectors can be used to extract content for the RSS feed:
 
 Each selector can have the following attributes:
 
-| Name           | Value                                                                                                              |
-| :------------- | :----------------------------------------------------------------------------------------------------------------- | ----------------- |
-| `selector`     | The CSS selector to select the element with the information.                                                       |
-| `extractor`    | The name of the extractor to use. See [Extractors]({{ '/ruby-gem/configuration/selectors/extractors'               | relative_url }}). |
-| `post_process` | An array of post processors to apply. See [Post Processors]({{ '/ruby-gem/configuration/selectors/post-processors' | relative_url }}). |
+| Name           | Value                                                                                                          |
+| :------------- | :------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `selector`     | The CSS selector to select the element with the information.                                                   |
+| `extractor`    | The name of the extractor to use. See [Extractors]({{ '/ruby-gem/reference/selectors/extractors'               | relative_url }}). |
+| `post_process` | An array of post processors to apply. See [Post Processors]({{ '/ruby-gem/reference/selectors/post-processors' | relative_url }}). |
 
 ---
 
diff --git a/ruby-gem/configuration/selectors/extractors.md b/ruby-gem/reference/selectors/extractors.md
similarity index 93%
rename from ruby-gem/configuration/selectors/extractors.md
rename to ruby-gem/reference/selectors/extractors.md
index 313c5300..0d438eec 100644
--- a/ruby-gem/configuration/selectors/extractors.md
+++ b/ruby-gem/reference/selectors/extractors.md
@@ -2,9 +2,8 @@
 layout: default
 title: Extractors
 parent: Selectors
-grand_parent: Configuration
 nav_order: 1
-permalink: /ruby-gem/configuration/selectors/extractors
+permalink: /ruby-gem/reference/selectors/extractors
 ---
 
 # Extractors
diff --git a/ruby-gem/configuration/selectors/post-processors.md b/ruby-gem/reference/selectors/post-processors.md
similarity index 94%
rename from ruby-gem/configuration/selectors/post-processors.md
rename to ruby-gem/reference/selectors/post-processors.md
index 4faab9a1..78131a57 100644
--- a/ruby-gem/configuration/selectors/post-processors.md
+++ b/ruby-gem/reference/selectors/post-processors.md
@@ -2,9 +2,8 @@
 layout: default
 title: Post Processors
 parent: Selectors
-grand_parent: Configuration
 nav_order: 2
-permalink: /ruby-gem/configuration/selectors/post-processors
+permalink: /ruby-gem/reference/selectors/post-processors
 ---
 
 # Post Processors
diff --git a/ruby-gem/configuration/strategy.md b/ruby-gem/reference/strategy.md
similarity index 97%
rename from ruby-gem/configuration/strategy.md
rename to ruby-gem/reference/strategy.md
index 7e9d549f..a4f6b5f5 100644
--- a/ruby-gem/configuration/strategy.md
+++ b/ruby-gem/reference/strategy.md
@@ -2,9 +2,9 @@
 layout: default
 title: Strategy
 nav_order: 4
-parent: Configuration
+parent: Reference
 grand_parent: Ruby Gem
-permalink: /ruby-gem/configuration/strategy
+permalink: /ruby-gem/reference/strategy
 ---
 
 # `strategy`
@@ -52,7 +52,7 @@ BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000" BROWSERLESS_IO_API_TOKEN="6R0
   html2rss feed --strategy=browserless the_the_config.yml
 ```
 
-> [!TIP]
+> 👉 TIP:  
 > When running locally with commands from above, you can skip setting the environment variables, as they are aligned with the default values from above example.
 
 ### Usage examples in feed config
diff --git a/ruby-gem/configuration/stylesheets.md b/ruby-gem/reference/stylesheets.md
similarity index 95%
rename from ruby-gem/configuration/stylesheets.md
rename to ruby-gem/reference/stylesheets.md
index 1d35efc7..6d9393d3 100644
--- a/ruby-gem/configuration/stylesheets.md
+++ b/ruby-gem/reference/stylesheets.md
@@ -2,9 +2,9 @@
 layout: default
 title: Stylesheets
 nav_order: 5
-parent: Configuration
+parent: Reference
 grand_parent: Ruby Gem
-permalink: /ruby-gem/configuration/stylesheets
+permalink: /ruby-gem/reference/stylesheets
 ---
 
 # `stylesheets`
diff --git a/ruby-gem/getting-started.md b/ruby-gem/tutorials/getting-started.md
similarity index 87%
rename from ruby-gem/getting-started.md
rename to ruby-gem/tutorials/getting-started.md
index f6fa16bf..dbcc35ae 100644
--- a/ruby-gem/getting-started.md
+++ b/ruby-gem/tutorials/getting-started.md
@@ -1,9 +1,9 @@
 ---
 layout: default
 title: Getting Started
-nav_order: 1
+nav_order: 2
 parent: Ruby Gem
-permalink: /ruby-gem/getting-started
+permalink: /ruby-gem/tutorials/getting-started
 ---
 
 # Getting Started with the html2rss Gem
@@ -18,9 +18,9 @@ We've designed this guide to be as straightforward as possible, whether you're a
 
 We recommend starting with the installation guide to set up `html2rss` on your system. Once installed, proceed to our step-by-step guide to creating your first feed. It covers everything from the simplest "no-config" method to creating a custom feed with CSS selectors.
 
-[**⚙️ Start with Installation**]({{ '/ruby-gem/installation' | relative_url }})
+[**⚙️ Start with Installation**]({{ '/ruby-gem/tutorials/installation' | relative_url }})
 
-[**🚀 Then, move to the "Your First Feed" Guide**]({{ '/ruby-gem/your-first-feed' | relative_url }})
+[**🚀 Then, move to the "Your First Feed" Guide**]({{ '/ruby-gem/tutorials/your-first-feed' | relative_url }})
 
 ---
 
@@ -28,7 +28,7 @@ We recommend starting with the installation guide to set up `html2rss` on your s
 
 For those looking for the quickest way to get started, `html2rss` offers an automatic method (`auto_source`) that intelligently scrapes a page to find content. This approach requires minimal setup and is perfect for a rapid start.
 
-[**⚡️ Learn about the "Automatic Generation" Method**]({{ '/ruby-gem/your-first-feed/#step-1-the-no-config-method-auto' | relative_url }})
+[**⚡️ Learn about the "Automatic Generation" Method**]({{ '/ruby-gem/tutorials/your-first-feed/#step-1-the-no-config-method-auto' | relative_url }})
 
 ---
 
diff --git a/ruby-gem/installation.md b/ruby-gem/tutorials/installation.md
similarity index 94%
rename from ruby-gem/installation.md
rename to ruby-gem/tutorials/installation.md
index 6bed934a..72dca21f 100644
--- a/ruby-gem/installation.md
+++ b/ruby-gem/tutorials/installation.md
@@ -2,8 +2,8 @@
 layout: default
 title: Installation
 nav_order: 2
-parent: Ruby Gem
-permalink: /ruby-gem/installation
+parent: Tutorials
+permalink: /ruby-gem/tutorials/installation
 ---
 
 # Installation
@@ -70,4 +70,4 @@ You should see the installed version number. If you encounter any issues, please
 
 ### Next Steps
 
-Now that html2rss is installed, let's create your [first RSS feed]({{ '/ruby-gem/your-first-feed' | relative_url }})!
+Now that html2rss is installed, let's create your [first RSS feed]({{ '/ruby-gem/tutorials/your-first-feed' | relative_url }})!
diff --git a/ruby-gem/your-first-feed.md b/ruby-gem/tutorials/your-first-feed.md
similarity index 96%
rename from ruby-gem/your-first-feed.md
rename to ruby-gem/tutorials/your-first-feed.md
index 0c05ce36..fd59e5b3 100644
--- a/ruby-gem/your-first-feed.md
+++ b/ruby-gem/tutorials/your-first-feed.md
@@ -2,8 +2,8 @@
 layout: default
 title: Your First Feed
 nav_order: 3
-parent: Ruby Gem
-permalink: /ruby-gem/your-first-feed
+parent: Tutorials
+permalink: /ruby-gem/tutorials/your-first-feed
 ---
 
 # Your First Feed: A Step-by-Step Guide
diff --git a/support/contact.md b/support/contact.md
deleted file mode 100644
index 61299582..00000000
--- a/support/contact.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-layout: default
-title: Contact
-nav_order: 9
----
-
-# Contact & Support
-
-We're here to help! If you have questions, feedback, or need assistance with `html2rss`, please use the following channels.
-
----
-
-### 1. GitHub Issues
-
-For bug reports, feature requests, or general technical questions, the best place to get support is by opening an issue on our GitHub repository:
-
-[**➡️ Open an Issue on GitHub**](https://github.com/html2rss/html2rss/issues)
-
-When opening an issue, please provide as much detail as possible, including:
-
-- The `html2rss` version you are using.
-- Your operating system.
-- Your configuration file (if applicable).
-- The target URL you are trying to scrape.
-- Any error messages you receive.
-- Steps to reproduce the issue.
-
----
-
-### 2. Community Discussions
-
-Join our community discussions on [GitHub Discussions](https://github.com/orgs/html2rss/discussions) to chat with other users and contributors. This is a great place for general questions, sharing tips, and discussing ideas.
-
----
-
-We look forward to hearing from you!
diff --git a/web-application/guides/deployment.md b/web-application/guides/deployment.md
deleted file mode 100644
index cc19fa66..00000000
--- a/web-application/guides/deployment.md
+++ /dev/null
@@ -1,32 +0,0 @@
----
-layout: default
-title: Deploying to Production
-nav_order: 2
-permalink: /web-application/guides/deployment
-parent: Guides
-grand_parent: Web Application
----
-
-# Deploying to Production
-
-This app is published on Docker Hub and therefore easy to use with Docker.
-The `docker-compose.yml` from the [Getting Started guide]({{ '/web-application/getting-started' | relative_url }}) is a good starting point.
-
-If you're going to host a public instance, _please, please, please_:
-
-- Put the application behind a reverse proxy.
-- Allow outside connections only via HTTPS.
-- Have an auto-update strategy (e.g., watchtower).
-- Monitor your `/health_check.txt` endpoint.
-- [Let the world know and add your instance to the wiki](https://github.com/html2rss/html2rss-web/wiki/Instances) -- thank you!
-
-## Versioning and Releases
-
-This web application is distributed in a [rolling release](https://en.wikipedia.org/wiki/Rolling_release) fashion from the `master` branch.
-
-For the latest commit passing GitHub CI/CD on the master branch, an updated Docker image will be pushed to [Docker Hub: `gilcreator/html2rss-web`](https://hub.docker.com/r/gilcreator/html2rss-web).
-The [SBOM](https://en.wikipedia.org/wiki/Software_supply_chain) is embedded in the Docker image.
-
-GitHub's @dependabot is enabled for dependency updates and they are automatically merged to the `master` branch when the CI gives the green light.
-
-If you use Docker, you should update to the latest image automatically by [setting up _watchtower_ as described]({{ '/web-application/guides/automatic-updates' | relative_url }}).
diff --git a/web-application/guides/automatic-updates.md b/web-application/how-to/automatic-updates.md
similarity index 73%
rename from web-application/guides/automatic-updates.md
rename to web-application/how-to/automatic-updates.md
index 4b97d139..ca4d2e6d 100644
--- a/web-application/guides/automatic-updates.md
+++ b/web-application/how-to/automatic-updates.md
@@ -2,8 +2,8 @@
 layout: default
 title: Automatic Updates
 nav_order: 3
-permalink: /web-application/guides/automatic-updates
-parent: Guides
+permalink: /web-application/how-to/automatic-updates
+parent: How-To Guides
 grand_parent: Web Application
 ---
 
@@ -11,4 +11,4 @@ grand_parent: Web Application
 
 The [watchtower](https://containrrr.dev/watchtower/) service automatically pulls running Docker images and checks for updates. If an update is available, it will automatically start the updated image with the same configuration as the running one. Please read its manual.
 
-The `docker-compose.yml` in the [Getting Started guide]({{ '/web-application/getting-started' | relative_url }}) contains a service description for watchtower.
+The `docker-compose.yml` in the [Getting Started guide]({{ '/web-application/tutorials' | relative_url }}) contains a service description for watchtower.
diff --git a/web-application/how-to/deployment.md b/web-application/how-to/deployment.md
new file mode 100644
index 00000000..3dea1d53
--- /dev/null
+++ b/web-application/how-to/deployment.md
@@ -0,0 +1,23 @@
+---
+layout: default
+title: Deploying to Production
+nav_order: 2
+permalink: /web-application/how-to/deployment
+parent: How-To Guides
+grand_parent: Web Application
+---
+
+# Deploying to Production
+
+This app is published on Docker Hub and therefore easy to use with Docker.
+The `docker-compose.yml` from the [Getting Started guide]({{ '/web-application/tutorials' | relative_url }}) is a good starting point.
+
+If you're going to host a public instance, _please, please, please_:
+
+- Put the application behind a reverse proxy.
+- Allow outside connections only via HTTPS.
+- Have an auto-update strategy (e.g., watchtower).
+- Monitor your `/health_check.txt` endpoint.
+- [Let the world know and add your instance to the wiki](https://github.com/html2rss/html2rss-web/wiki/Instances) -- thank you!
+
+For information on the web application's versioning and release strategy, please refer to the [main Web Application overview]({{ '/web-application' | relative_url }}).
diff --git a/web-application/guides/index.md b/web-application/how-to/index.md
similarity index 70%
rename from web-application/guides/index.md
rename to web-application/how-to/index.md
index 1412e9a2..aeca5aa6 100644
--- a/web-application/guides/index.md
+++ b/web-application/how-to/index.md
@@ -1,12 +1,12 @@
 ---
 layout: default
-title: Guides
+title: How-To Guides
 nav_order: 2
-permalink: /web-application/guides
+permalink: /web-application/how-to
 parent: Web Application
 has_children: true
 ---
 
-# Guides
+# How-To Guides
 
 This section contains detailed, task-based guides for users who want to go beyond the basics.
diff --git a/web-application/guides/monitoring.md b/web-application/how-to/monitoring.md
similarity index 94%
rename from web-application/guides/monitoring.md
rename to web-application/how-to/monitoring.md
index 298732b1..57679f36 100644
--- a/web-application/guides/monitoring.md
+++ b/web-application/how-to/monitoring.md
@@ -2,8 +2,8 @@
 layout: default
 title: Monitoring
 nav_order: 4
-permalink: /web-application/guides/monitoring
-parent: Guides
+permalink: /web-application/how-to/monitoring
+parent: How-To Guides
 grand_parent: Web Application
 ---
 
diff --git a/web-application/index.md b/web-application/index.md
index 29adc171..f88670f5 100644
--- a/web-application/index.md
+++ b/web-application/index.md
@@ -18,3 +18,14 @@ This web application scrapes websites to build and deliver RSS 2.0 feeds.
 - **Caching:** Handles request caching and sets caching-related HTTP headers.
 
 The functionality of scraping websites and building the RSS feeds is provided by the Ruby gem [`html2rss`](https://github.com/html2rss/html2rss).
+
+## Versioning and Releases
+
+This web application is distributed in a [rolling release](https://en.wikipedia.org/wiki/Rolling_release) fashion from the `master` branch.
+
+For the latest commit passing GitHub CI/CD on the master branch, an updated Docker image will be pushed to [Docker Hub: `gilcreator/html2rss-web`](https://hub.docker.com/r/gilcreator/html2rss-web).
+The [SBOM](https://en.wikipedia.org/wiki/Software_supply_chain) is embedded in the Docker image.
+
+GitHub's @dependabot is enabled for dependency updates and they are automatically merged to the `master` branch when the CI gives the green light.
+
+If you use Docker, you should update to the latest image automatically by [setting up _watchtower_ as described]({{ '/web-application/how-to/automatic-updates' | relative_url }}).
diff --git a/web-application/reference/configuration.md b/web-application/reference/env-variables.md
similarity index 95%
rename from web-application/reference/configuration.md
rename to web-application/reference/env-variables.md
index de28add6..f92d4746 100644
--- a/web-application/reference/configuration.md
+++ b/web-application/reference/env-variables.md
@@ -1,8 +1,7 @@
 ---
 layout: default
-title: Configuration
+title: ENV variables
 nav_order: 1
-permalink: /web-application/reference/configuration
 parent: Reference
 grand_parent: Web Application
 ---
diff --git a/web-application/getting-started/index.md b/web-application/tutorials/index.md
similarity index 90%
rename from web-application/getting-started/index.md
rename to web-application/tutorials/index.md
index 80f5bd31..401791b3 100644
--- a/web-application/getting-started/index.md
+++ b/web-application/tutorials/index.md
@@ -1,12 +1,12 @@
 ---
 layout: default
-title: Getting Started
+title: Tutorials
 nav_order: 1
-permalink: /web-application/getting-started
+permalink: /web-application/tutorials
 parent: Web Application
 ---
 
-# Getting Started with html2rss-web
+# Tutorials: Getting Started with html2rss-web
 
 In this guide, you'll launch the `html2rss-web` application on your local machine. By the end, you'll have a running instance and your first live RSS feed.
 
@@ -64,11 +64,11 @@ touch feeds.yml
 ### 3. Launch the Application
 
 ```bash
-docker-compose up
+docker compose up
 ```
 
 Congratulations! The `html2rss-web` application is now running. Open your browser to `http://localhost:3000` to see it in action.
 
 ### Next Up
 
-Now that you have the application running, let's [create your first custom feed]({{ '/web-application/guides/creating-custom-feeds' | relative_url }}).
+Now that you have the application running, let's [create your first custom feed]({{ '/web-application/how-to/creating-custom-feeds' | relative_url }}).

From 919c47b08ee9502d6789f5a469fd332cc63a5f21 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 26 Jul 2025 16:50:32 +0200
Subject: [PATCH 08/17] refactor: update documentation for clarity and
 consistency

---
 feed-directory/index.html             | 53 +++++++++++++--------------
 index.md                              |  2 +-
 ruby-gem/index.md                     |  2 +-
 ruby-gem/tutorials/installation.md    |  1 +
 ruby-gem/tutorials/your-first-feed.md |  1 +
 web-application/index.md              |  2 +-
 web-application/tutorials/index.md    |  4 +-
 7 files changed, 32 insertions(+), 33 deletions(-)

diff --git a/feed-directory/index.html b/feed-directory/index.html
index e286c561..53c2ae42 100644
--- a/feed-directory/index.html
+++ b/feed-directory/index.html
@@ -87,35 +87,32 @@ <h3 class="card-title mb-0 text-mono fs-5">
         {%- endif -%}
       </div>
       <div class="card-body">
-        <details>
-          <summary>Details</summary>
-          <dl>
-            {%- if config.channel.url -%}
-            <dt>URL to scrape</dt>
-            <dd>
-              {%- if config.valid_channel_url -%}
-              <a
-                href="{{ config.channel.url }}"
-                class="config__url"
-                target="_blank"
-                rel="noopener noreferrer"
-                >{{ config.channel.url }}</a
-              >
-              {%- else -%}
-              <span class="config__url"
-                >{{ config.channel.url | xml_escape }}</span
-              >
-              {%- endif -%}
-            </dd>
-            {%- endif -%} {%- if config.channel.time_zone -%}
-            <dt>Time zone</dt>
-            <dd>{{ config.channel.time_zone }}</dd>
-            {%- endif -%} {%- if config.channel.language -%}
-            <dt>Language</dt>
-            <dd>{{ config.channel.language }}</dd>
+        <dl>
+          {%- if config.channel.url -%}
+          <dt>URL to scrape</dt>
+          <dd>
+            {%- if config.valid_channel_url -%}
+            <a
+              href="{{ config.channel.url }}"
+              class="config__url"
+              target="_blank"
+              rel="noopener noreferrer"
+              >{{ config.channel.url }}</a
+            >
+            {%- else -%}
+            <span class="config__url"
+              >{{ config.channel.url | xml_escape }}</span
+            >
             {%- endif -%}
-          </dl>
-        </details>
+          </dd>
+          {%- endif -%} {%- if config.channel.time_zone -%}
+          <dt>Time zone</dt>
+          <dd>{{ config.channel.time_zone }}</dd>
+          {%- endif -%} {%- if config.channel.language -%}
+          <dt>Language</dt>
+          <dd>{{ config.channel.language }}</dd>
+          {%- endif -%}
+        </dl>
 
         {%- if config.valid_channel_url -%}
         <div class="mt-4 d-flex-justify-content-between">
diff --git a/index.md b/index.md
index f4d7f28b..d2f9942a 100644
--- a/index.md
+++ b/index.md
@@ -27,7 +27,7 @@ The `html2rss` project is more than just a single tool. It's a collection of too
 
 - **[html2rss-web]({{ '/web-application' | relative_url }}):** A user-friendly web application that makes it easy to create, manage, and share RSS feeds. This is the recommended starting point for most users.
 - **[html2rss (Ruby Gem)]({{ '/ruby-gem' | relative_url }}):** The core library that powers the web application. It provides a powerful and flexible command-line interface for creating custom RSS feeds.
-- **[html2rss-configs](https://github.com/html2rss/html2rss-configs):** A community-driven repository of pre-built feed configurations for popular websites, so you can get started quickly.
+- **[Feed Directory]({{ '/feed-directory' | relative_url }}):** A public listing of RSS feeds for websites of interest, powered by community-driven configurations.
 
 ---
 
diff --git a/ruby-gem/index.md b/ruby-gem/index.md
index 6a2ff54c..206a0d58 100644
--- a/ruby-gem/index.md
+++ b/ruby-gem/index.md
@@ -6,7 +6,7 @@ has_children: true
 permalink: /ruby-gem
 ---
 
-# The html2rss Ruby Gem
+# The html2rss Ruby Gem ([GitHub Repo](https://github.com/html2rss/html2rss))
 
 This section provides detailed documentation for the `html2rss` Ruby gem. The gem is the core library that powers the `html2rss-web` application.
 
diff --git a/ruby-gem/tutorials/installation.md b/ruby-gem/tutorials/installation.md
index 72dca21f..e1b55633 100644
--- a/ruby-gem/tutorials/installation.md
+++ b/ruby-gem/tutorials/installation.md
@@ -3,6 +3,7 @@ layout: default
 title: Installation
 nav_order: 2
 parent: Tutorials
+grand_parent: Ruby Gem
 permalink: /ruby-gem/tutorials/installation
 ---
 
diff --git a/ruby-gem/tutorials/your-first-feed.md b/ruby-gem/tutorials/your-first-feed.md
index fd59e5b3..531a48f4 100644
--- a/ruby-gem/tutorials/your-first-feed.md
+++ b/ruby-gem/tutorials/your-first-feed.md
@@ -3,6 +3,7 @@ layout: default
 title: Your First Feed
 nav_order: 3
 parent: Tutorials
+grand_parent: Ruby Gem
 permalink: /ruby-gem/tutorials/your-first-feed
 ---
 
diff --git a/web-application/index.md b/web-application/index.md
index f88670f5..37099e26 100644
--- a/web-application/index.md
+++ b/web-application/index.md
@@ -8,7 +8,7 @@ permalink: /web-application
 
 # html2rss-web
 
-This web application scrapes websites to build and deliver RSS 2.0 feeds.
+This web application scrapes websites to build and deliver RSS 2.0 feeds. ([GitHub Repo](https://github.com/html2rss/html2rss-web))
 
 ## Features
 
diff --git a/web-application/tutorials/index.md b/web-application/tutorials/index.md
index 401791b3..cfca84f6 100644
--- a/web-application/tutorials/index.md
+++ b/web-application/tutorials/index.md
@@ -1,12 +1,12 @@
 ---
 layout: default
-title: Tutorials
+title: Getting Started
 nav_order: 1
 permalink: /web-application/tutorials
 parent: Web Application
 ---
 
-# Tutorials: Getting Started with html2rss-web
+# Getting Started with html2rss-web
 
 In this guide, you'll launch the `html2rss-web` application on your local machine. By the end, you'll have a running instance and your first live RSS feed.
 

From 0f5a6ba2aba078a8745551f9f3221376c8cd7cc3 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 27 Jul 2025 20:43:00 +0200
Subject: [PATCH 09/17] feat: enhance feed directory with Alpine.js integration

---
 assets/js/feed-directory/index.js | 206 ++++++------------------------
 feed-directory/index.html         |  89 ++++++++++---
 get-involved/index.md             |   4 +-
 3 files changed, 112 insertions(+), 187 deletions(-)

diff --git a/assets/js/feed-directory/index.js b/assets/js/feed-directory/index.js
index 6e380bcc..d8d97f90 100644
--- a/assets/js/feed-directory/index.js
+++ b/assets/js/feed-directory/index.js
@@ -1,171 +1,49 @@
-const App = {
-  init() {
-    this.instanceEl = document.querySelector('input[name="instance"]');
-    if (!this.instanceEl) return;
-
-    this.searchEl = document.querySelector('input[name="search"]');
-    this.configsEl = document.querySelector("#configs");
-    this.cards = this.configsEl.querySelectorAll(".card");
-    this.bindEvents();
-    this.updateInstanceUrl();
-    this.initDynamicForms();
-  },
-
-  bindEvents() {
-    this.searchEl.addEventListener("input", this.filterConfigs.bind(this));
-    this.configsEl.addEventListener("click", (event) => {
-      const { bindClick } = event.target.dataset;
-      if (bindClick === "show") {
-        this.handleShowClick(event);
-      } else if (bindClick === "copy") {
-        this.handleCopyClick(event);
+document.addEventListener("alpine:init", () => {
+  Alpine.data("feedDirectory", () => ({
+    instanceUrl: "https://html2rss.herokuapp.com/",
+    searchQuery: "",
+    configs: window.feedDirectoryData,
+
+    filterConfig(configName) {
+      if (!this.searchQuery) {
+        return true;
       }
-    });
-
-    this.instanceEl.addEventListener("blur", this.updateInstanceUrl.bind(this));
-  },
-
-  filterConfigs() {
-    const query = this.searchEl.value.toLowerCase();
-    this.cards.forEach((card) => {
-      const title = card.querySelector(".card-title").innerText.toLowerCase();
-      if (title.includes(query)) {
-        card.style.display = "";
-      } else {
-        card.style.display = "none";
+      return configName.toLowerCase().includes(this.searchQuery.toLowerCase());
+    },
+
+    getFeedUrl(config, params = {}) {
+      let url = this.instanceUrl.endsWith("/")
+        ? this.instanceUrl
+        : `${this.instanceUrl}/`;
+      url += `${config.domain}/${config.name}.rss`;
+
+      const queryParams = new URLSearchParams();
+      if (Array.isArray(config.url_parameters)) {
+        config.url_parameters.forEach((param) => {
+          const key = param[0];
+          if (params[key]) {
+            queryParams.append(key, params[key]);
+          }
+        });
       }
-    });
-  },
-
-  getInstanceUrl() {
-    const url = this.instanceEl.value;
-    return url.endsWith("/") ? url : `${url}/`;
-  },
 
-  updateInstanceUrl() {
-    const url = this.getInstanceUrl();
-    document.querySelectorAll(".instance").forEach((el) => {
-      if (el instanceof HTMLElement) {
-        el.innerText = url;
+      const queryString = queryParams.toString();
+      if (queryString) {
+        url += `?${queryString}`;
       }
-    });
-  },
-
-  handleShowClick(event) {
-    const { target } = event;
-    const path = this.getPath(target);
-    if (path) {
-      target.href = `${this.getInstanceUrl()}${path}`;
-    } else {
-      event.preventDefault();
-    }
-  },
-
-  async handleCopyClick(event) {
-    const { target } = event;
-    const path = this.getPath(target);
-    if (!path) return;
-
-    const href = `${this.getInstanceUrl()}${path}`;
-
-    try {
-      await navigator.clipboard.writeText(href);
-      this.showCopiedState(target);
-    } catch (err) {
-      console.error("Failed to copy: ", err);
-    }
-  },
-
-  showCopiedState(triggerEl) {
-    triggerEl.classList.add("copied");
-    setTimeout(() => {
-      triggerEl.classList.remove("copied");
-      triggerEl.blur();
-    }, 1000);
-  },
-
-  initDynamicForms() {
-    document
-      .querySelectorAll("[data-dynamic-form]")
-      .forEach((formContainer) => {
-        const form = formContainer.querySelector("form");
-        const pathPreview = formContainer.querySelector("[data-path-preview]");
-        const actionButtons = formContainer.querySelectorAll(
-          "[data-path-template]",
-        );
-
-        if (!form || !pathPreview || !(pathPreview instanceof HTMLElement))
-          return;
-
-        const updateDynamicPath = () => {
-          const formData = new FormData(form);
-          const firstButton = actionButtons[0];
-          if (!(firstButton instanceof HTMLElement)) return;
 
-          let pathTemplate = firstButton.dataset.pathTemplate || "";
-          let pathPreviewTemplate = pathTemplate;
-
-          for (const [key, value] of formData.entries()) {
-            if (typeof value === "string") {
-              const placeholder = `{${key}}`;
-              pathTemplate = pathTemplate.replace(
-                placeholder,
-                encodeURIComponent(value),
-              );
-              pathPreviewTemplate = pathPreviewTemplate.replace(
-                placeholder,
-                value || `{${key}}`,
-              );
-            }
-          }
-
-          actionButtons.forEach((button) => {
-            if (button instanceof HTMLElement) {
-              button.dataset.path = pathTemplate;
-            }
-          });
-          pathPreview.innerText = pathPreviewTemplate;
-        };
-
-        form.addEventListener("input", updateDynamicPath);
-        updateDynamicPath(); // Initial update
+      return url;
+    },
+
+    copyUrl(config, params = {}, event) {
+      const url = this.getFeedUrl(config, params);
+      navigator.clipboard.writeText(url).then(() => {
+        const originalText = event.target.innerHTML;
+        event.target.innerHTML = "Copied!";
+        setTimeout(() => {
+          event.target.innerHTML = originalText;
+        }, 2000);
       });
-  },
-
-  getPath(target) {
-    if (!(target instanceof HTMLElement)) return null;
-
-    if (target.dataset.path) {
-      return target.dataset.path;
-    }
-
-    if (target.dataset.pathTemplate) {
-      const formContainer = target.closest("[data-dynamic-form]");
-      if (!formContainer) return null;
-
-      const form = formContainer.querySelector("form");
-      if (!form) return null;
-
-      const formData = new FormData(form);
-      let path = target.dataset.pathTemplate;
-      let allParamsFilled = true;
-
-      for (const [key, value] of formData.entries()) {
-        if (!value) {
-          allParamsFilled = false;
-        }
-        if (typeof value === "string") {
-          path = path.replace(`{${key}}`, encodeURIComponent(value));
-        }
-      }
-
-      return allParamsFilled ? path : null;
-    }
-
-    return null;
-  },
-};
-
-document.addEventListener("DOMContentLoaded", () => {
-  App.init();
+    },
+  }));
 });
diff --git a/feed-directory/index.html b/feed-directory/index.html
index 53c2ae42..d43bc2ff 100644
--- a/feed-directory/index.html
+++ b/feed-directory/index.html
@@ -50,14 +50,20 @@ <h2 class="fs-6">What is an Instance URL?</h2>
   </span>
 </noscript>
 
-<div id="configs">
+<script>
+  // Define global data for Alpine.js to consume, processed by Jekyll
+  // The `site.data.configs` is already JSONified by Jekyll, so we just need to assign it.
+  window.feedDirectoryData = {{ site.data.configs | jsonify }};
+</script>
+
+<div id="configs" x-data="feedDirectory()">
   <fieldset class="mb-4 py-1 px-2">
     <legend class="fs-5">Instance URL</legend>
 
     <input
       type="text"
       name="instance"
-      value="https://1.h2r.workers.dev"
+      x-model="instanceUrl"
       class="bg-grey-dk-100 p-2"
     />
   </fieldset>
@@ -69,13 +75,17 @@ <h2 class="fs-6">What is an Instance URL?</h2>
       type="search"
       name="search"
       placeholder="e.g. heise"
+      x-model="searchQuery"
       class="bg-grey-dk-100 p-2"
     />
   </fieldset>
 
   <div class="card-deck">
     {% for config in site.data.configs %}
-    <div class="card mb-4">
+    <div
+      class="card mb-4"
+      x-show="filterConfig('{{ config.domain }}/{{ config.name }}')"
+    >
       <div class="card-header d-flex-justify-content-between">
         <h3 class="card-title mb-0 text-mono fs-5">
           {{ config.domain }}/{{ config.name }}
@@ -118,15 +128,14 @@ <h3 class="card-title mb-0 text-mono fs-5">
         <div class="mt-4 d-flex-justify-content-between">
           <a
             href="#"
-            data-bind-click="show"
-            data-path="{{ config.domain }}/{{ config.name }}.rss"
+            x-bind:href="getFeedUrl(JSON.parse('{{ config | jsonify | escape }}'))"
             class="btn btn-primary"
             rel="noopener noreferrer"
+            target="_blank"
             >Show RSS</a
           >
           <button
-            data-bind-click="copy"
-            data-path="{{ config.domain }}/{{ config.name }}.rss"
+            x-on:click.prevent="copyUrl(JSON.parse('{{ config | jsonify | escape }}'), {}, $event)"
             class="btn btn-icon"
             rel="noopener noreferrer"
             title="Copy URL"
@@ -142,7 +151,40 @@ <h3 class="card-title mb-0 text-mono fs-5">
           </a>
         </div>
         {%- else -%}
-        <div class="mt-4" data-dynamic-form>
+        <div
+          class="mt-4"
+          x-data="{ params: {}, pathPreview: '' }"
+          x-init="
+          const currentConfig = JSON.parse('{{ config | jsonify | escape }}');
+          console.log('{{ config | jsonify | escape }}');
+          $watch('params', () => {
+            let template = `${currentConfig.domain}/${currentConfig.name}.rss?`;
+            let previewTemplate = template;
+            if (Array.isArray(currentConfig.url_parameters)) {
+              currentConfig.url_parameters.forEach(param => {
+                const key = param[0];
+                const value = params[key];
+                template += `${key}=${encodeURIComponent(value || '')}&`;
+                previewTemplate += `${key}=${value || `{${param[1]}}`}&`;
+              });
+              template = template.slice(0, -1); // Remove trailing '&'
+              previewTemplate = previewTemplate.slice(0, -1); // Remove trailing '&'
+            }
+            pathPreview = previewTemplate;
+            $refs.showBtn.href = getFeedUrl(currentConfig, params);
+            $refs.copyBtn.dataset.url = getFeedUrl(currentConfig, params);
+          });
+          $nextTick(() => {
+            let initialParams = {};
+            if (Array.isArray(currentConfig.url_parameters)) {
+              currentConfig.url_parameters.forEach(param => {
+                initialParams[param[0]] = '';
+              });
+            }
+            params = initialParams;
+          });
+        "
+        >
           <form>
             {% for param in config.url_parameters %}
             <div class="form-group">
@@ -155,7 +197,7 @@ <h3 class="card-title mb-0 text-mono fs-5">
                 name="{{ param[0] }}"
                 class="form-control"
                 placeholder="{{ param[1] }}"
-                data-param
+                x-model="params.{{ param[0] }}"
               />
             </div>
             {% endfor %}
@@ -163,18 +205,19 @@ <h3 class="card-title mb-0 text-mono fs-5">
           <div class="mt-2 d-flex-justify-content-between">
             <a
               href="#"
-              data-bind-click="show"
-              data-path-template="{{ config.domain }}/{{ config.name }}.rss?{% for param in config.url_parameters %}{{ param[0] }}={{ ob }}{{ param[0] }}{{ cb }}&{% endfor %}"
+              x-bind:href="getFeedUrl(JSON.parse('{{ config | jsonify | escape }}'), params)"
               class="btn btn-primary"
               rel="noopener noreferrer"
+              target="_blank"
+              x-ref="showBtn"
               >Show RSS</a
             >
             <button
-              data-bind-click="copy"
-              data-path-template="{{ config.domain }}/{{ config.name }}.rss?{% for param in config.url_parameters %}{{ param[0] }}={{ ob }}{{ param[0] }}{{ cb }}&{% endfor %}"
+              x-on:click.prevent="copyUrl(JSON.parse('{{ config | jsonify | escape }}'), params, $event)"
               class="btn btn-icon"
               rel="noopener noreferrer"
               title="Copy URL"
+              x-ref="copyBtn"
             >
               <svg><use xlink:href="#copy-icon"></use></svg>
             </button>
@@ -188,12 +231,11 @@ <h3 class="card-title mb-0 text-mono fs-5">
           </div>
           <div class="mt-2">
             <code class="d-block w-100 p-2 bg-grey-dk-300 text-grey-dk-000">
-              <span class="instance"></span
-              ><span data-path-preview
-                >{{ config.domain }}/{{ config.name }}.rss?{% for param in
-                config.url_parameters %}{{ param[0] }}={{ ob }}{{ param[1] }}{{
-                cb }}&{% endfor %}</span
-              >
+              <span
+                class="instance"
+                x-text="instanceUrl.endsWith('/') ? instanceUrl : instanceUrl + '/'"
+              ></span
+              ><span x-text="pathPreview"></span>
             </code>
           </div>
         </div>
@@ -222,4 +264,11 @@ <h2 class="fs-6">Contribute to the Directory</h2>
   </a>
 </div>
 
-<script src="/assets/js/feed-directory/index.js" async defer></script>
+<script
+  src="{{ '/assets/js/feed-directory/index.js' | relative_url }}"
+  defer
+></script>
+<script
+  defer
+  src="https://cdn.jsdelivr.net/npm/alpinejs@3.14.1/dist/cdn.min.js"
+></script>
diff --git a/get-involved/index.md b/get-involved/index.md
index d26c871c..dfde4685 100644
--- a/get-involved/index.md
+++ b/get-involved/index.md
@@ -9,12 +9,10 @@ nav_order: 4
 
 Want to participate in the `html2rss` project? Explore the options below to engage with our community and contribute to the project's growth.
 
----
-
+- [**The Project Roadmap**]({{ 'https://github.com/orgs/html2rss/projects/3/views/1' }}): See what's being worked on, planned, and needs attention across all `html2rss` components.
 - [**Report Bugs & Discuss Features**]({{ '/get-involved/issues-and-features' | relative_url }}): Found a bug or have a new feature idea? Learn where to report and discuss them.
 - [**Join Community Discussions**]({{ '/get-involved/discussions' | relative_url }}): Connect with other users and contributors, ask questions, and share ideas.
 - [**Contribute to html2rss**]({{ '/contributing' | relative_url }}): Ready to contribute code, documentation, or feed configurations? Find detailed guides here.
-- [**📊 View Project Roadmap & Tasks**]({{ 'https://github.com/orgs/html2rss/projects/3/views/1' }}): See what's being worked on, planned, and needs attention across all `html2rss` projects.
 
 ---
 

From 8945974c2214879f78285104529b71421543349b Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 27 Jul 2025 21:38:16 +0200
Subject: [PATCH 10/17] feat: style feed directory component

---
 _sass/custom/_feed-directory.scss |  85 +++++++++
 assets/css/sass/base.scss         |   2 +
 feed-directory/index.html         | 279 +++++++++++++-----------------
 3 files changed, 211 insertions(+), 155 deletions(-)
 create mode 100644 _sass/custom/_feed-directory.scss

diff --git a/_sass/custom/_feed-directory.scss b/_sass/custom/_feed-directory.scss
new file mode 100644
index 00000000..aaa6456f
--- /dev/null
+++ b/_sass/custom/_feed-directory.scss
@@ -0,0 +1,85 @@
+.feed-directory__item {
+  border: 1px solid var(--border-color);
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  border-radius: 8px;
+  background-color: var(--main-bg-color);
+  align-items: center; /* Vertically align items in the center */
+}
+
+.feed-directory__item-info {
+  display: flex;
+  flex-direction: column;
+  flex-grow: 1;
+  margin-right: 1rem;
+}
+
+.feed-directory__item-name {
+  font-family: var(--mono-font-family);
+  font-size: 1.2rem;
+  font-weight: bold;
+  margin-bottom: 0; /* Remove bottom margin to reduce vertical space */
+  color: var(--text-color);
+}
+
+.feed-directory__item-url {
+  color: var(--text-color);
+  margin-bottom: 1rem;
+  word-break: break-all;
+}
+
+.feed-directory__item-actions {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  flex-shrink: 0;
+}
+
+.feed-directory__item-actions__rss-icon {
+  width: 24px;
+  height: 24px;
+}
+
+.feed-directory__item-actions__edit-link {
+  font-size: 0.9rem;
+  white-space: nowrap;
+}
+
+.feed-directory__item-param-form {
+  margin-top: 1rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--border-color);
+}
+
+.feed-directory__item-param-form__group {
+  /* Add styles if needed */
+}
+
+.feed-directory__item-param-form__label {
+  /* Add styles if needed */
+}
+
+.feed-directory__item-param-form__input {
+  /* Add styles if needed */
+}
+
+.feed-directory__item-param-form__code {
+  /* Add styles if needed */
+}
+
+.feed-directory__item-param-form__code-instance {
+  /* Add styles if needed */
+}
+
+.feed-directory__item-param-form__code-path-preview {
+  /* Add styles if needed */
+}
+
+.feed-directory__fieldset {
+  /* Add styles if needed */
+}
+
+.feed-directory__input {
+  /* Add styles if needed */
+}
diff --git a/assets/css/sass/base.scss b/assets/css/sass/base.scss
index 0b12a7e5..719f7766 100644
--- a/assets/css/sass/base.scss
+++ b/assets/css/sass/base.scss
@@ -134,3 +134,5 @@ summary {
 summary:hover {
   color: var(--link-color);
 }
+
+@import "custom/feed-directory";
diff --git a/feed-directory/index.html b/feed-directory/index.html
index d43bc2ff..5cc5c741 100644
--- a/feed-directory/index.html
+++ b/feed-directory/index.html
@@ -16,9 +16,9 @@ <h1 class="fs-9">Welcome to the Feed Directory!</h1>
 <div class="mt-6">
   <h2 class="fs-6">What is an Instance URL?</h2>
   <p>
-    An "Instance URL" is the address of a running `html2rss-web` application.
-    You can use a publicly available instance or, for a more decentralized and
-    robust web, you can host your own.
+    An "Instance URL" is the address of a running
+    <code>html2rss-web</code> application. You can use a publicly available
+    instance or host your own.
   </p>
   <p>
     By hosting your own instance, you contribute to the resilience of the
@@ -35,211 +35,180 @@ <h2 class="fs-6">What is an Instance URL?</h2>
     <a
       href="https://github.com/html2rss/html2rss-web/wiki/Instances"
       target="_blank"
-      >community-run wiki</a
+      rel="noopener noreferrer"
+    >
+      community-run wiki</a
     >.
   </p>
 </div>
 
 <hr class="my-6" />
 
-{%- assign ob = '{' -%} {%- assign cb = '}' -%}
-
 <noscript>
-  <span class="noscript">
-    This site needs JavaScript to link to the feed URL!
-  </span>
+  <span class="noscript"
+    >This site needs JavaScript to link to the feed URL!</span
+  >
 </noscript>
 
 <script>
-  // Define global data for Alpine.js to consume, processed by Jekyll
-  // The `site.data.configs` is already JSONified by Jekyll, so we just need to assign it.
   window.feedDirectoryData = {{ site.data.configs | jsonify }};
 </script>
 
+<svg style="display: none">
+  <symbol id="copy-icon" viewBox="0 0 24 24" fill="currentColor">
+    <path
+      d="M16 1H4c-1.1 0-2 .9-2 2v14h2V3h12V1zm3 4H8c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h11c1.1 0 2-.9 2-2V7c0-1.1-.9-2-2-2zm0 16H8V7h11v14z"
+    />
+  </symbol>
+</svg>
+
 <div id="configs" x-data="feedDirectory()">
-  <fieldset class="mb-4 py-1 px-2">
+  <fieldset class="feed-directory__fieldset mb-4 py-1 px-2">
     <legend class="fs-5">Instance URL</legend>
-
     <input
       type="text"
       name="instance"
       x-model="instanceUrl"
-      class="bg-grey-dk-100 p-2"
+      class="feed-directory__input bg-grey-dk-100 p-2"
+      aria-label="Instance URL"
     />
   </fieldset>
 
-  <fieldset class="mb-4 py-1 px-2">
+  <fieldset class="feed-directory__fieldset mb-4 py-1 px-2">
     <legend class="fs-5">Search</legend>
-
     <input
       type="search"
       name="search"
       placeholder="e.g. heise"
       x-model="searchQuery"
-      class="bg-grey-dk-100 p-2"
+      class="feed-directory__input bg-grey-dk-100 p-2"
+      aria-label="Search feeds"
     />
   </fieldset>
 
-  <div class="card-deck">
+  <div>
     {% for config in site.data.configs %}
     <div
-      class="card mb-4"
-      x-show="filterConfig('{{ config.domain }}/{{ config.name }}')"
+      class="feed-directory__item"
+      x-show="filterConfig('{{ config.domain | escape }}/{{ config.name | escape }}')"
+      x-data="{ configIndex: {{ forloop.index0 }}, params: {}, pathPreview: '', copied: false }"
+      x-init="
+        const currentConfig = window.feedDirectoryData[configIndex];
+        {%- unless config.valid_channel_url -%}
+        $watch('params', (value) => {
+          let previewTemplate = `${currentConfig.domain}/${currentConfig.name}.rss?`;
+          if (Array.isArray(currentConfig.url_parameters)) {
+            currentConfig.url_parameters.forEach(param => {
+              const key = param[0];
+              const val = value[key];
+              previewTemplate += `${key}=${val || `{${param[1]}}`}&`;
+            });
+            previewTemplate = previewTemplate.slice(0, -1);
+          }
+          pathPreview = previewTemplate;
+        });
+        $nextTick(() => {
+          let initialParams = {};
+          if (Array.isArray(currentConfig.url_parameters)) {
+            currentConfig.url_parameters.forEach(param => {
+              initialParams[param[0]] = '';
+            });
+          }
+          params = initialParams;
+        });
+        {%- endunless -%}
+      "
+      x-cloak
     >
-      <div class="card-header d-flex-justify-content-between">
-        <h3 class="card-title mb-0 text-mono fs-5">
-          {{ config.domain }}/{{ config.name }}
-        </h3>
-        {%- if config.valid_channel_url -%}
-        <span class="badge text-green-000">Ready to use</span>
-        {%- else -%}
-        <span class="badge text-yellow-000">Requires parameters</span>
-        {%- endif -%}
-      </div>
-      <div class="card-body">
-        <dl>
-          {%- if config.channel.url -%}
-          <dt>URL to scrape</dt>
-          <dd>
-            {%- if config.valid_channel_url -%}
-            <a
-              href="{{ config.channel.url }}"
-              class="config__url"
-              target="_blank"
-              rel="noopener noreferrer"
-              >{{ config.channel.url }}</a
-            >
-            {%- else -%}
-            <span class="config__url"
-              >{{ config.channel.url | xml_escape }}</span
-            >
-            {%- endif -%}
-          </dd>
-          {%- endif -%} {%- if config.channel.time_zone -%}
-          <dt>Time zone</dt>
-          <dd>{{ config.channel.time_zone }}</dd>
-          {%- endif -%} {%- if config.channel.language -%}
-          <dt>Language</dt>
-          <dd>{{ config.channel.language }}</dd>
-          {%- endif -%}
-        </dl>
-
-        {%- if config.valid_channel_url -%}
-        <div class="mt-4 d-flex-justify-content-between">
+      <div class="feed-directory__item-info">
+        {% if config.channel.url %}
+        <h3 class="feed-directory__item-name">
+          {% if config.valid_channel_url %}
           <a
-            href="#"
-            x-bind:href="getFeedUrl(JSON.parse('{{ config | jsonify | escape }}'))"
-            class="btn btn-primary"
-            rel="noopener noreferrer"
+            href="{{ config.channel.url | escape }}"
             target="_blank"
-            >Show RSS</a
-          >
-          <button
-            x-on:click.prevent="copyUrl(JSON.parse('{{ config | jsonify | escape }}'), {}, $event)"
-            class="btn btn-icon"
             rel="noopener noreferrer"
-            title="Copy URL"
-          >
-            <svg><use xlink:href="#copy-icon"></use></svg>
-          </button>
-          <a
-            href="https://github.com/html2rss/html2rss-configs/blob/master/lib/html2rss/configs/{{ config.domain }}/{{ config.name }}.yml"
-            class="btn"
-            target="_blank"
           >
-            View YAML
+            {{ config.channel.url | escape }}
           </a>
-        </div>
-        {%- else -%}
-        <div
-          class="mt-4"
-          x-data="{ params: {}, pathPreview: '' }"
-          x-init="
-          const currentConfig = JSON.parse('{{ config | jsonify | escape }}');
-          console.log('{{ config | jsonify | escape }}');
-          $watch('params', () => {
-            let template = `${currentConfig.domain}/${currentConfig.name}.rss?`;
-            let previewTemplate = template;
-            if (Array.isArray(currentConfig.url_parameters)) {
-              currentConfig.url_parameters.forEach(param => {
-                const key = param[0];
-                const value = params[key];
-                template += `${key}=${encodeURIComponent(value || '')}&`;
-                previewTemplate += `${key}=${value || `{${param[1]}}`}&`;
-              });
-              template = template.slice(0, -1); // Remove trailing '&'
-              previewTemplate = previewTemplate.slice(0, -1); // Remove trailing '&'
-            }
-            pathPreview = previewTemplate;
-            $refs.showBtn.href = getFeedUrl(currentConfig, params);
-            $refs.copyBtn.dataset.url = getFeedUrl(currentConfig, params);
-          });
-          $nextTick(() => {
-            let initialParams = {};
-            if (Array.isArray(currentConfig.url_parameters)) {
-              currentConfig.url_parameters.forEach(param => {
-                initialParams[param[0]] = '';
-              });
-            }
-            params = initialParams;
-          });
-        "
-        >
-          <form>
+          {% else %}
+          <span>{{ config.channel.url | escape }}</span>
+          {% endif %}
+        </h3>
+        {% endif %} {% unless config.valid_channel_url %}
+        <div class="feed-directory__item-param-form">
+          <form role="form">
             {% for param in config.url_parameters %}
-            <div class="form-group">
-              <label for="{{ config.domain }}-{{ config.name }}-{{ param[0] }}"
-                >{{ param[0] }}</label
+            <div class="feed-directory__item-param-form__group form-group">
+              <label
+                for="{{ config.domain | escape }}-{{ config.name | escape }}-{{ param[0] | escape }}"
+                class="feed-directory__item-param-form__label"
               >
+                {{ param[0] | escape }}
+              </label>
               <input
                 type="text"
-                id="{{ config.domain }}-{{ config.name }}-{{ param[0] }}"
-                name="{{ param[0] }}"
-                class="form-control"
-                placeholder="{{ param[1] }}"
-                x-model="params.{{ param[0] }}"
+                id="{{ config.domain | escape }}-{{ config.name | escape }}-{{ param[0] | escape }}"
+                name="{{ param[0] | escape }}"
+                class="feed-directory__item-param-form__input form-control"
+                placeholder="{{ param[1] | escape }}"
+                x-model="params['{{ param[0] }}']"
+                aria-label="{{ param[0] | escape }}"
               />
             </div>
             {% endfor %}
           </form>
-          <div class="mt-2 d-flex-justify-content-between">
-            <a
-              href="#"
-              x-bind:href="getFeedUrl(JSON.parse('{{ config | jsonify | escape }}'), params)"
-              class="btn btn-primary"
-              rel="noopener noreferrer"
-              target="_blank"
-              x-ref="showBtn"
-              >Show RSS</a
-            >
-            <button
-              x-on:click.prevent="copyUrl(JSON.parse('{{ config | jsonify | escape }}'), params, $event)"
-              class="btn btn-icon"
-              rel="noopener noreferrer"
-              title="Copy URL"
-              x-ref="copyBtn"
-            >
-              <svg><use xlink:href="#copy-icon"></use></svg>
-            </button>
-            <a
-              href="https://github.com/html2rss/html2rss-configs/blob/master/lib/html2rss/configs/{{ config.domain }}/{{ config.name }}.yml"
-              class="btn"
-              target="_blank"
-            >
-              View YAML
-            </a>
-          </div>
           <div class="mt-2">
-            <code class="d-block w-100 p-2 bg-grey-dk-300 text-grey-dk-000">
+            <code
+              class="feed-directory__item-param-form__code d-block w-100 p-2 bg-grey-dk-300 text-grey-dk-000"
+            >
               <span
                 class="instance"
                 x-text="instanceUrl.endsWith('/') ? instanceUrl : instanceUrl + '/'"
-              ></span
-              ><span x-text="pathPreview"></span>
+              ></span>
+              <span x-text="pathPreview"></span>
             </code>
           </div>
         </div>
-        {%- endif -%}
+        {% endunless %}
+      </div>
+
+      <div class="feed-directory__item-actions">
+        <a
+          :href="getFeedUrl(currentConfig, params)"
+          rel="noopener noreferrer"
+          target="_blank"
+          title="Show RSS"
+          aria-label="Open RSS feed"
+        >
+          <svg
+            class="rss-icon"
+            viewBox="0 0 24 24"
+            fill="currentColor"
+            width="24"
+            height="24"
+            xmlns="http://www.w3.org/2000/svg"
+          >
+            <path
+              d="M19.199 2.001H4.801C3.805 2.001 3 2.805 3 3.801v15.398c0 .996.805 1.801 1.801 1.801h14.398c.996 0 1.801-.805 1.801-1.801V3.801c0-.996-.805-1.8-1.801-1.8zm-1.501 15.4c-1.38 0-2.5-1.12-2.5-2.5 0-1.379 1.12-2.5 2.5-2.5s2.5 1.121 2.5 2.5c0 1.38-1.12 2.5-2.5 2.5zm.001-6.5c-3.154 0-5.738 2.584-5.738 5.738 0 .552.447 1 1 1s1-.448 1-1c0-2.031 1.638-3.669 3.669-3.669.553 0 1-.448 1-1s-.447-1-1-1zm0-6.5c-6.191 0-11.238 5.047-11.238 11.238 0 .552.447 1 1 1s1-.448 1-1c0-5.088 4.15-9.238 9.238-9.238.553 0 1-.448 1-1s-.447-1-1-1z"
+            />
+          </svg>
+        </a>
+        <button
+          class="btn btn-icon"
+          aria-label="Copy URL"
+          @click.prevent="copyUrl(currentConfig, params, $event); copied = true; setTimeout(() => copied = false, 1500)"
+          :title="copied ? 'Copied!' : 'Copy URL'"
+        >
+          <svg><use xlink:href="#copy-icon"></use></svg>
+        </button>
+        <a
+          href="https://github.com/html2rss/html2rss-configs/blob/master/lib/html2rss/configs/{{ config.domain | uri_escape }}/{{ config.name | uri_escape }}.yml"
+          class="edit-link"
+          target="_blank"
+        >
+          Edit on GitHub
+        </a>
       </div>
     </div>
     {% endfor %}
@@ -269,6 +238,6 @@ <h2 class="fs-6">Contribute to the Directory</h2>
   defer
 ></script>
 <script
-  defer
   src="https://cdn.jsdelivr.net/npm/alpinejs@3.14.1/dist/cdn.min.js"
+  defer
 ></script>

From 93d5de5e21131649f9d8e931859980f8ee33bc66 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Tue, 29 Jul 2025 19:24:46 +0200
Subject: [PATCH 11/17] feat(feed-directory): present form for dynamic params
 [wip]

Signed-off-by: Gil Desmarais <git@desmarais.de>
---
 _includes/head_custom.html          |  46 +++++++-
 _sass/custom/_feed-directory.scss   |  85 --------------
 assets/css/main.scss                |   2 +-
 assets/css/sass/base.scss           | 119 +++----------------
 assets/css/sass/feed-directory.scss | 138 ++++++++++++++++++++++
 assets/js/feed-directory/index.js   |  75 +++++++++---
 feed-directory/index.html           | 173 ++++++++++++----------------
 7 files changed, 329 insertions(+), 309 deletions(-)
 delete mode 100644 _sass/custom/_feed-directory.scss
 create mode 100644 assets/css/sass/feed-directory.scss

diff --git a/_includes/head_custom.html b/_includes/head_custom.html
index 1f8e9070..1972ed66 100644
--- a/_includes/head_custom.html
+++ b/_includes/head_custom.html
@@ -63,13 +63,47 @@
   async
   src="//gc.zgo.at/count.js"
 ></script>
-<svg xmlns="http://www.w3.org/2000/svg" style="display: none">
-  <symbol id="copy-icon" viewBox="0 0 16 16">
+<div class="svg-defs-hidden">
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" id="rss-icon">
+    <rect
+      width="512"
+      height="512"
+      x="-512"
+      y="-512"
+      rx="70"
+      ry="70"
+      style="fill: #ea7819; fill-opacity: 1; stroke: none"
+      transform="scale(-1)"
+    />
+    <path
+      d="M81.056 267.05c43.705 0 84.79 17.072 115.665 48.124 30.931 31.051 47.961 72.411 47.961 116.44h67.35c0-127.885-103.62-231.921-230.976-231.921zm.106-119.4c155.76 0 282.488 127.42 282.488 284.049H431C431 237.925 274.054 80.301 81.162 80.301zm93.135 236.998c0 25.757-20.892 46.649-46.649 46.649-25.756 0-46.648-20.885-46.648-46.649C81 358.878 101.885 338 127.641 338c25.757 0 46.656 20.878 46.656 20.878"
+      style="fill: #fff"
+    />
+  </svg>
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" id="edit-icon">
+    <path
+      fill="currentColor"
+      d="M3 17.25V21h3.75L18.75 9.75l-3.75-3.75L3 17.25zM20.71 7.04c.39-.39.39-1.02 0-1.41l-2.34-2.34c-.39-.39-1.02-.39-1.41 0l-1.83 1.83 3.75 3.75 1.83-1.83z"
+    />
+  </svg>
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 32 32"
+    id="settings-icon"
+  >
+    <path
+      fill="currentColor"
+      d="M28 13V8a2 2 0 0 0-2-2h-3v2h3v5a3.98 3.98 0 0 0 1.382 3A3.98 3.98 0 0 0 26 19v5h-3v2h3a2 2 0 0 0 2-2v-5a2 2 0 0 1 2-2v-2a2 2 0 0 1-2-2"
+    />
     <path
-      d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"
+      fill="currentColor"
+      d="m17 9-.857 3h2L19 9h2l-.857 3H22v2h-2.428l-1.143 4H21v2h-3.143L17 23h-2l.857-3h-2L13 23h-2l.857-3H10v-2h2.429l1.143-4H11v-2h3.143L15 9Zm.572 5h-2l-1.143 4h2Z"
+      style="fill-rule: evenodd"
     />
     <path
-      d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zM9 2H7v.5a.5.5 0 0 0 .5.5h1a.5.5 0 0 0 .5-.5V2z"
+      fill="currentColor"
+      d="M6 13V8h3V6H6a2 2 0 0 0-2 2v5a2 2 0 0 1-2 2v2a2 2 0 0 1 2 2v5a2 2 0 0 0 2 2h3v-2H6v-5a3.98 3.98 0 0 0-1.382-3A3.98 3.98 0 0 0 6 13"
     />
-  </symbol>
-</svg>
+    <path d="M0 0h32v32H0z" style="fill: none" />
+  </svg>
+</div>
diff --git a/_sass/custom/_feed-directory.scss b/_sass/custom/_feed-directory.scss
deleted file mode 100644
index aaa6456f..00000000
--- a/_sass/custom/_feed-directory.scss
+++ /dev/null
@@ -1,85 +0,0 @@
-.feed-directory__item {
-  border: 1px solid var(--border-color);
-  display: flex;
-  justify-content: space-between;
-  align-items: flex-start;
-  border-radius: 8px;
-  background-color: var(--main-bg-color);
-  align-items: center; /* Vertically align items in the center */
-}
-
-.feed-directory__item-info {
-  display: flex;
-  flex-direction: column;
-  flex-grow: 1;
-  margin-right: 1rem;
-}
-
-.feed-directory__item-name {
-  font-family: var(--mono-font-family);
-  font-size: 1.2rem;
-  font-weight: bold;
-  margin-bottom: 0; /* Remove bottom margin to reduce vertical space */
-  color: var(--text-color);
-}
-
-.feed-directory__item-url {
-  color: var(--text-color);
-  margin-bottom: 1rem;
-  word-break: break-all;
-}
-
-.feed-directory__item-actions {
-  display: flex;
-  align-items: center;
-  gap: 1rem;
-  flex-shrink: 0;
-}
-
-.feed-directory__item-actions__rss-icon {
-  width: 24px;
-  height: 24px;
-}
-
-.feed-directory__item-actions__edit-link {
-  font-size: 0.9rem;
-  white-space: nowrap;
-}
-
-.feed-directory__item-param-form {
-  margin-top: 1rem;
-  padding-top: 1rem;
-  border-top: 1px solid var(--border-color);
-}
-
-.feed-directory__item-param-form__group {
-  /* Add styles if needed */
-}
-
-.feed-directory__item-param-form__label {
-  /* Add styles if needed */
-}
-
-.feed-directory__item-param-form__input {
-  /* Add styles if needed */
-}
-
-.feed-directory__item-param-form__code {
-  /* Add styles if needed */
-}
-
-.feed-directory__item-param-form__code-instance {
-  /* Add styles if needed */
-}
-
-.feed-directory__item-param-form__code-path-preview {
-  /* Add styles if needed */
-}
-
-.feed-directory__fieldset {
-  /* Add styles if needed */
-}
-
-.feed-directory__input {
-  /* Add styles if needed */
-}
diff --git a/assets/css/main.scss b/assets/css/main.scss
index 4495a031..c76854d5 100644
--- a/assets/css/main.scss
+++ b/assets/css/main.scss
@@ -8,6 +8,6 @@
 // @import files directly from the sass/ directory:;
 
 @import "base";
-
+@import "feed-directory";
 // Don't write any SCSS in this file as stylelint does not fix it,
 // just use the sass directory.
diff --git a/assets/css/sass/base.scss b/assets/css/sass/base.scss
index 719f7766..9c95075f 100644
--- a/assets/css/sass/base.scss
+++ b/assets/css/sass/base.scss
@@ -16,24 +16,22 @@
   --transition-shadow: box-shadow 0.2s ease-in-out;
 }
 
-#configs input[name="instance"],
-#configs input[name="search"] {
-  width: 100%;
+details {
+  transition: all 0.2s ease-in-out;
+}
+
+summary {
+  cursor: pointer;
+  outline: none;
 }
 
-.js__copy-element {
-  position: fixed;
-  top: 0;
-  left: 0;
-  width: 0;
-  height: 0;
-  pointer-events: none;
-  user-select: text;
-  opacity: 0;
+summary:hover {
+  color: var(--link-color);
 }
 
-.js__copy-element::selection {
-  background-color: transparent;
+#configs input[name="instance"],
+#configs input[name="search"] {
+  inline-size: 100%;
 }
 
 .noscript {
@@ -44,95 +42,6 @@
   border: 1px solid var(--color-error);
 }
 
-button[data-bind-click="copy"] {
-  padding: var(--button-padding-y) var(--button-padding-x);
-  font: inherit;
-  line-height: 1.2;
-  color: var(--color-text);
-  cursor: pointer;
-  border: 2px solid transparent;
-  border-radius: var(--border-radius-sm);
-  transition: var(--transition-border), var(--transition-shadow);
-}
-
-button[data-bind-click="copy"]:focus-visible {
-  outline: 2px dashed var(--color-accent);
-  outline-offset: 2px;
-}
-
-button[data-bind-click="copy"].copied,
-button[data-bind-click="copy"].copied:hover,
-button[data-bind-click="copy"].copied:active {
-  border-color: var(--color-accent);
-  box-shadow: inset 0 2px 4px var(--color-accent-bg);
-}
-
-.card-deck {
-  display: flex;
-  flex-wrap: wrap;
-}
-
-.card {
-  width: 100%;
-}
-.card-header {
-  padding: 0.75rem 1.25rem;
-  margin-bottom: 0;
-  background-color: var(--table-background-color);
-  border-bottom: 1px solid var(--border-color);
-  position: relative;
-}
-
-.card-body {
-  padding: 1.25rem;
-}
-.badge {
-  position: absolute;
-  right: 0;
-  animation: 0;
-
-  display: inline-block;
-  padding: 0.2em 0.4em;
-  font-size: 75%;
-  border-radius: 0.25rem;
-  vertical-align: middle;
-  white-space: nowrap;
-}
-
-.btn-icon {
-  padding: 0.1rem 0.2rem;
-  font-size: 0.8rem;
-  line-height: 1;
-  border-radius: var(--border-radius);
-  background-color: transparent;
-  border: 1px solid transparent;
-  color: var(--link-color);
-}
-
-.btn-icon svg {
-  width: 1em;
-  height: 1em;
-  vertical-align: -0.125em;
-  fill: currentColor;
-}
-
-.d-flex-justify-content-between {
-  display: flex;
-  justify-content: space-between;
-  align-items: center;
-}
-
-details {
-  transition: all 0.2s ease-in-out;
-}
-
-summary {
-  cursor: pointer;
-  outline: none;
-}
-
-summary:hover {
-  color: var(--link-color);
+.svg-defs-hidden {
+  display: none;
 }
-
-@import "custom/feed-directory";
diff --git a/assets/css/sass/feed-directory.scss b/assets/css/sass/feed-directory.scss
new file mode 100644
index 00000000..0da2a9ea
--- /dev/null
+++ b/assets/css/sass/feed-directory.scss
@@ -0,0 +1,138 @@
+.feed-directory__filters {
+  position: sticky;
+  top: 0;
+  height: fit-content;
+  z-index: 2;
+
+  border: 1px solid var(--border-color);
+  border-radius: var(--border-radius);
+  margin-bottom: var(--spacing-lg);
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--spacing-lg);
+  align-items: flex-start;
+}
+
+.feed-directory__item {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: var(--spacing-sm);
+
+  padding: var(--spacing-sm);
+  border: 1px solid var(--border-color);
+  border-radius: var(--border-radius);
+
+  transition: var(--transition-base);
+}
+
+.feed-directory__item:hover {
+  box-shadow: var(--box-shadow);
+}
+
+.feed-directory__item-info {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  gap: var(--spacing-xs);
+  margin-inline-end: var(--spacing-sm);
+}
+
+h3.feed-directory__item-name {
+  font-size: var(--font-size-h4);
+  font-weight: var(--font-weight-bold);
+  color: var(--color-text);
+  margin: 0;
+  padding: 0;
+}
+
+.feed-directory__item-url {
+  font-size: var(--font-size-sm);
+  color: var(--color-text-light);
+  word-break: break-word;
+  margin: 0;
+}
+
+.feed-directory__item-param-form__buttons {
+  display: flex;
+  justify-content: flex-end;
+}
+
+.feed-directory__item-actions {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-sm);
+  flex-shrink: 0;
+}
+
+.feed-directory__item-actions button {
+  background-color: unset;
+  border: 1px;
+  text-align: center;
+  padding: 0;
+  cursor: pointer;
+}
+
+.feed-directory__item-actions__rss-icon,
+.feed-directory__item-actions__edit-icon,
+.feed-directory__item-actions__settings-icon {
+  inline-size: 1.2rem;
+  block-size: 1.2rem;
+}
+
+.feed-directory__item-actions__rss-icon:hover,
+.feed-directory__item-actions__edit-icon:hover,
+.feed-directory__item-actions__settings-icon:hover {
+  color: var(--link-color);
+}
+
+.feed-directory__fieldset {
+  border: none;
+  padding: 0;
+  flex: 1 1 45%;
+  min-width: 280px;
+  margin-bottom: 0;
+}
+
+.feed-directory__fieldset legend {
+  padding: 0 var(--spacing-xs);
+  margin-bottom: var(--spacing-sm);
+}
+
+.feed-directory__item-param-form {
+  margin-block-start: var(--spacing-sm);
+  padding-block-start: var(--spacing-sm);
+  border-block-start: 1px solid var(--border-color);
+}
+
+.feed-directory__item-param-form__group {
+  margin-block-end: var(--spacing-xs);
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-sm);
+}
+
+.feed-directory__item-param-form__label {
+  font-size: 0.85em;
+  font-weight: var(--font-weight-normal);
+  color: var(--color-text);
+  flex-shrink: 0;
+  min-width: 80px;
+}
+
+.feed-directory__item-param-form__input {
+  inline-size: 100%;
+  padding: var(--spacing-xs) var(--spacing-sm);
+  border: 1px solid var(--border-color);
+  border-radius: var(--border-radius-sm);
+  color: var(--color-text);
+}
+
+.feed-directory__item-param-form__code {
+  font-size: var(--font-size-sm);
+  padding: var(--spacing-xs) var(--spacing-sm);
+  border-radius: var(--border-radius-sm);
+  background-color: var(--code-block-bg-color);
+  color: var(--code-block-color);
+  word-break: break-all;
+}
diff --git a/assets/js/feed-directory/index.js b/assets/js/feed-directory/index.js
index d8d97f90..010b5457 100644
--- a/assets/js/feed-directory/index.js
+++ b/assets/js/feed-directory/index.js
@@ -1,14 +1,29 @@
 document.addEventListener("alpine:init", () => {
   Alpine.data("feedDirectory", () => ({
-    instanceUrl: "https://html2rss.herokuapp.com/",
+    instanceUrl: atob("aHR0cHM6Ly8xLmgyci53b3JrZXJzLmRldi8="),
     searchQuery: "",
     configs: window.feedDirectoryData,
 
+    fuzzyMatch(text, query) {
+      const lowerText = text.toLowerCase();
+      const lowerQuery = query.toLowerCase();
+      let textIndex = 0;
+      let queryIndex = 0;
+
+      while (queryIndex < lowerQuery.length && textIndex < lowerText.length) {
+        if (lowerQuery[queryIndex] === lowerText[textIndex]) {
+          queryIndex++;
+        }
+        textIndex++;
+      }
+      return queryIndex === lowerQuery.length;
+    },
+
     filterConfig(configName) {
       if (!this.searchQuery) {
         return true;
       }
-      return configName.toLowerCase().includes(this.searchQuery.toLowerCase());
+      return this.fuzzyMatch(configName, this.searchQuery);
     },
 
     getFeedUrl(config, params = {}) {
@@ -18,13 +33,13 @@ document.addEventListener("alpine:init", () => {
       url += `${config.domain}/${config.name}.rss`;
 
       const queryParams = new URLSearchParams();
-      if (Array.isArray(config.url_parameters)) {
-        config.url_parameters.forEach((param) => {
-          const key = param[0];
+
+      if (config.url_parameters) {
+        for (const key of Object.keys(config.url_parameters)) {
           if (params[key]) {
             queryParams.append(key, params[key]);
           }
-        });
+        }
       }
 
       const queryString = queryParams.toString();
@@ -34,16 +49,48 @@ document.addEventListener("alpine:init", () => {
 
       return url;
     },
+  }));
 
-    copyUrl(config, params = {}, event) {
-      const url = this.getFeedUrl(config, params);
-      navigator.clipboard.writeText(url).then(() => {
-        const originalText = event.target.innerHTML;
-        event.target.innerHTML = "Copied!";
-        setTimeout(() => {
-          event.target.innerHTML = originalText;
-        }, 2000);
+  Alpine.data("feedItemData", (index) => ({
+    config: window.feedDirectoryData[index],
+    params: {},
+    pathPreview: "",
+    showParamsForm: false,
+    toggleParamsForm() {
+      this.showParamsForm = !this.showParamsForm;
+    },
+    dynamicParamsInterpolate(string, params) {
+      return string.replace(/%<(\w+)>s/g, (_, key) => {
+        if (!(key in params)) {
+          throw new Error(`Missing value for placeholder: ${key}`);
+        }
+        return params[key];
       });
     },
+
+    init() {
+      if (!this.config) return;
+      if (!this.config.valid_channel_url) {
+        this.$watch("params", (value) => {
+          let params = {};
+
+          Object.entries(this.config.url_parameters).forEach(
+            ([key, fallback]) => {
+              const val = value[key];
+              params[key] = val || `{${fallback}}`;
+            },
+          );
+
+          try {
+            this.pathPreview = this.dynamicParamsInterpolate(
+              this.config.channel.url,
+              params,
+            );
+          } catch (error) {
+            console.error("Error interpolating parameters:", error);
+          }
+        });
+      }
+    },
   }));
 });
diff --git a/feed-directory/index.html b/feed-directory/index.html
index 5cc5c741..125c3f51 100644
--- a/feed-directory/index.html
+++ b/feed-directory/index.html
@@ -14,24 +14,20 @@ <h1 class="fs-9">Welcome to the Feed Directory!</h1>
 </div>
 
 <div class="mt-6">
-  <h2 class="fs-6">What is an Instance URL?</h2>
+  <h2 class="fs-6">Instance URL</h2>
   <p>
     An "Instance URL" is the address of a running
-    <code>html2rss-web</code> application. You can use a publicly available
-    instance or host your own.
-  </p>
-  <p>
-    By hosting your own instance, you contribute to the resilience of the
-    html2rss ecosystem and help keep the web open and accessible to everyone.
+    <code>html2rss-web</code> application. You can use a public instance, but we
+    encourage you to host your own.
   </p>
   <a
-    href="{{ '/web-application/guides/deployment' | relative_url }}"
+    href="{{ '/web-application/how-to/self-hosting' | relative_url }}"
     class="btn btn-primary"
   >
-    🚀 Host Your Own Instance
+    🚀 Host Your Own Instance (and share it!)
   </a>
   <p class="mt-2">
-    Or, find a publicly available instance on the
+    Find more public instances on the
     <a
       href="https://github.com/html2rss/html2rss-web/wiki/Instances"
       target="_blank"
@@ -54,70 +50,40 @@ <h2 class="fs-6">What is an Instance URL?</h2>
   window.feedDirectoryData = {{ site.data.configs | jsonify }};
 </script>
 
-<svg style="display: none">
-  <symbol id="copy-icon" viewBox="0 0 24 24" fill="currentColor">
-    <path
-      d="M16 1H4c-1.1 0-2 .9-2 2v14h2V3h12V1zm3 4H8c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h11c1.1 0 2-.9 2-2V7c0-1.1-.9-2-2-2zm0 16H8V7h11v14z"
-    />
-  </symbol>
-</svg>
-
 <div id="configs" x-data="feedDirectory()">
-  <fieldset class="feed-directory__fieldset mb-4 py-1 px-2">
-    <legend class="fs-5">Instance URL</legend>
-    <input
-      type="text"
-      name="instance"
-      x-model="instanceUrl"
-      class="feed-directory__input bg-grey-dk-100 p-2"
-      aria-label="Instance URL"
-    />
-  </fieldset>
-
-  <fieldset class="feed-directory__fieldset mb-4 py-1 px-2">
-    <legend class="fs-5">Search</legend>
-    <input
-      type="search"
-      name="search"
-      placeholder="e.g. heise"
-      x-model="searchQuery"
-      class="feed-directory__input bg-grey-dk-100 p-2"
-      aria-label="Search feeds"
-    />
-  </fieldset>
+  <div class="feed-directory__filters bg-grey-dk-300">
+    <fieldset class="feed-directory__fieldset py-1 px-2">
+      <legend class="fs-5">Instance URL</legend>
+      <input
+        type="text"
+        name="instance"
+        x-model="instanceUrl"
+        class="feed-directory__input bg-grey-dk-100 p-2"
+        aria-label="Instance URL"
+      />
+    </fieldset>
 
+    <fieldset class="feed-directory__fieldset py-1 px-2">
+      <legend class="fs-5">Search</legend>
+      <input
+        type="search"
+        name="search"
+        autofocus
+        placeholder="fia, apple, news or blog"
+        x-on:input.debounce.500ms="searchQuery = $event.target.value"
+        x-model="searchQuery"
+        class="feed-directory__input bg-grey-dk-100 p-2"
+        aria-label="Search feeds"
+      />
+    </fieldset>
+  </div>
   <div>
     {% for config in site.data.configs %}
     <div
       class="feed-directory__item"
       x-show="filterConfig('{{ config.domain | escape }}/{{ config.name | escape }}')"
-      x-data="{ configIndex: {{ forloop.index0 }}, params: {}, pathPreview: '', copied: false }"
-      x-init="
-        const currentConfig = window.feedDirectoryData[configIndex];
-        {%- unless config.valid_channel_url -%}
-        $watch('params', (value) => {
-          let previewTemplate = `${currentConfig.domain}/${currentConfig.name}.rss?`;
-          if (Array.isArray(currentConfig.url_parameters)) {
-            currentConfig.url_parameters.forEach(param => {
-              const key = param[0];
-              const val = value[key];
-              previewTemplate += `${key}=${val || `{${param[1]}}`}&`;
-            });
-            previewTemplate = previewTemplate.slice(0, -1);
-          }
-          pathPreview = previewTemplate;
-        });
-        $nextTick(() => {
-          let initialParams = {};
-          if (Array.isArray(currentConfig.url_parameters)) {
-            currentConfig.url_parameters.forEach(param => {
-              initialParams[param[0]] = '';
-            });
-          }
-          params = initialParams;
-        });
-        {%- endunless -%}
-      "
+      x-data="feedItemData({{ forloop.index0 }})"
+      x-init="init()"
       x-cloak
     >
       <div class="feed-directory__item-info">
@@ -132,11 +98,16 @@ <h3 class="feed-directory__item-name">
             {{ config.channel.url | escape }}
           </a>
           {% else %}
-          <span>{{ config.channel.url | escape }}</span>
+          <span x-show="!pathPreview">{{ config.channel.url | escape }}</span>
+          <a
+            x-bind:href="pathPreview"
+            x-show="pathPreview"
+            x-text="pathPreview"
+          ></a>
           {% endif %}
         </h3>
         {% endif %} {% unless config.valid_channel_url %}
-        <div class="feed-directory__item-param-form">
+        <div class="feed-directory__item-param-form" x-show="showParamsForm">
           <form role="form">
             {% for param in config.url_parameters %}
             <div class="feed-directory__item-param-form__group form-group">
@@ -157,57 +128,63 @@ <h3 class="feed-directory__item-name">
               />
             </div>
             {% endfor %}
+            <div class="feed-directory__item-param-form__buttons">
+              <button x-on:click="showParamsForm = false" class="btn btn-sm">
+                Close
+              </button>
+            </div>
           </form>
-          <div class="mt-2">
-            <code
-              class="feed-directory__item-param-form__code d-block w-100 p-2 bg-grey-dk-300 text-grey-dk-000"
-            >
-              <span
-                class="instance"
-                x-text="instanceUrl.endsWith('/') ? instanceUrl : instanceUrl + '/'"
-              ></span>
-              <span x-text="pathPreview"></span>
-            </code>
-          </div>
         </div>
         {% endunless %}
       </div>
 
       <div class="feed-directory__item-actions">
+        {% if config.valid_channel_url %}
         <a
-          :href="getFeedUrl(currentConfig, params)"
+          :href="getFeedUrl(config, params)"
           rel="noopener noreferrer"
           target="_blank"
           title="Show RSS"
           aria-label="Open RSS feed"
         >
-          <svg
-            class="rss-icon"
-            viewBox="0 0 24 24"
-            fill="currentColor"
-            width="24"
-            height="24"
-            xmlns="http://www.w3.org/2000/svg"
-          >
-            <path
-              d="M19.199 2.001H4.801C3.805 2.001 3 2.805 3 3.801v15.398c0 .996.805 1.801 1.801 1.801h14.398c.996 0 1.801-.805 1.801-1.801V3.801c0-.996-.805-1.8-1.801-1.8zm-1.501 15.4c-1.38 0-2.5-1.12-2.5-2.5 0-1.379 1.12-2.5 2.5-2.5s2.5 1.121 2.5 2.5c0 1.38-1.12 2.5-2.5 2.5zm.001-6.5c-3.154 0-5.738 2.584-5.738 5.738 0 .552.447 1 1 1s1-.448 1-1c0-2.031 1.638-3.669 3.669-3.669.553 0 1-.448 1-1s-.447-1-1-1zm0-6.5c-6.191 0-11.238 5.047-11.238 11.238 0 .552.447 1 1 1s1-.448 1-1c0-5.088 4.15-9.238 9.238-9.238.553 0 1-.448 1-1s-.447-1-1-1z"
-            />
+          <svg class="feed-directory__item-actions__rss-icon">
+            <use xlink:href="#rss-icon"></use>
           </svg>
         </a>
+        {% else %}
         <button
-          class="btn btn-icon"
-          aria-label="Copy URL"
-          @click.prevent="copyUrl(currentConfig, params, $event); copied = true; setTimeout(() => copied = false, 1500)"
-          :title="copied ? 'Copied!' : 'Copy URL'"
+          x-show="!showParamsForm"
+          x-on:click="toggleParamsForm"
+          title="Start setting parameters and get the RSS URL"
+          aria-label="Start setting parameters and get the RSS URL"
         >
-          <svg><use xlink:href="#copy-icon"></use></svg>
+          <svg class="feed-directory__item-actions__settings-icon">
+            <use xlink:href="#settings-icon"></use>
+          </svg>
         </button>
+        <a
+          :href="getFeedUrl(config, params)"
+          rel="noopener noreferrer"
+          target="_blank"
+          title="Show RSS"
+          aria-label="Open RSS feed"
+          x-show="showParamsForm"
+        >
+          <svg class="feed-directory__item-actions__rss-icon">
+            <use xlink:href="#rss-icon"></use>
+          </svg>
+        </a>
+        {% endif %}
         <a
           href="https://github.com/html2rss/html2rss-configs/blob/master/lib/html2rss/configs/{{ config.domain | uri_escape }}/{{ config.name | uri_escape }}.yml"
           class="edit-link"
           target="_blank"
+          title="Edit on GitHub"
+          aria-label="Edit on GitHub"
         >
-          Edit on GitHub
+          <svg class="feed-directory__item-actions__edit-icon">
+            <use xlink:href="#edit-icon"></use>
+          </svg>
         </a>
       </div>
     </div>

From 1c7701146c5f4e216c6f9d35aebe5443a4134f0c Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 2 Aug 2025 13:21:43 +0200
Subject: [PATCH 12/17] feat: reorder ruby-gem contents & dedupe

---
 get-involved/discussions.md                   |  1 -
 get-involved/issues-and-features.md           |  1 -
 index.md                                      |  2 +-
 .../how-to/advanced-content-extraction.md     |  1 -
 ruby-gem/how-to/creating-custom-feeds.md      | 16 ----
 ruby-gem/how-to/custom-http-requests.md       |  1 -
 ruby-gem/how-to/dynamic-parameters.md         |  1 -
 ruby-gem/how-to/handling-dynamic-content.md   |  1 -
 ruby-gem/how-to/index.md                      |  1 -
 ruby-gem/how-to/styling-rss-feed.md           |  1 -
 ruby-gem/index.md                             | 27 ++++--
 ruby-gem/{tutorials => }/installation.md      |  6 +-
 .../{auto_source.md => auto-source.md}        |  1 -
 ruby-gem/reference/channel.md                 |  1 -
 ruby-gem/reference/cli-reference.md           |  1 -
 ruby-gem/reference/headers.md                 |  1 -
 ruby-gem/reference/index.md                   |  2 +-
 ruby-gem/reference/selectors/extractors.md    |  1 -
 .../reference/selectors/post-processors.md    |  1 -
 ruby-gem/tutorials/getting-started.md         | 42 ---------
 ruby-gem/tutorials/index.md                   | 11 +++
 .../{how-to => tutorials}/simple-blog-list.md |  9 +-
 ruby-gem/tutorials/your-first-feed.md         |  3 +-
 web-application/getting-started.md            | 28 ++++++
 web-application/how-to/automatic-updates.md   |  3 +-
 web-application/how-to/deployment.md          | 20 ++--
 web-application/how-to/index.md               |  3 +-
 web-application/how-to/monitoring.md          |  1 -
 web-application/index.md                      | 20 ++--
 web-application/installation.md               | 94 +++++++++++++++++++
 web-application/reference/index.md            |  3 +-
 web-application/tutorials/index.md            | 74 ---------------
 32 files changed, 181 insertions(+), 197 deletions(-)
 delete mode 100644 ruby-gem/how-to/creating-custom-feeds.md
 rename ruby-gem/{tutorials => }/installation.md (95%)
 rename ruby-gem/reference/{auto_source.md => auto-source.md} (97%)
 delete mode 100644 ruby-gem/tutorials/getting-started.md
 create mode 100644 ruby-gem/tutorials/index.md
 rename ruby-gem/{how-to => tutorials}/simple-blog-list.md (93%)
 create mode 100644 web-application/getting-started.md
 create mode 100644 web-application/installation.md
 delete mode 100644 web-application/tutorials/index.md

diff --git a/get-involved/discussions.md b/get-involved/discussions.md
index 54740a0b..3025e5f5 100644
--- a/get-involved/discussions.md
+++ b/get-involved/discussions.md
@@ -3,7 +3,6 @@ layout: default
 title: Join Community Discussions
 nav_order: 2
 parent: Get Involved
-permalink: /get-involved/discussions
 ---
 
 # Join Community Discussions
diff --git a/get-involved/issues-and-features.md b/get-involved/issues-and-features.md
index 3fb0bfa0..7cd9611a 100644
--- a/get-involved/issues-and-features.md
+++ b/get-involved/issues-and-features.md
@@ -3,7 +3,6 @@ layout: default
 title: Report Bugs & Discuss Features
 nav_order: 1
 parent: Get Involved
-permalink: /get-involved/issues-and-features
 ---
 
 # Report Bugs & Discuss Features
diff --git a/index.md b/index.md
index d2f9942a..49242eb1 100644
--- a/index.md
+++ b/index.md
@@ -14,7 +14,7 @@ Tired of missing updates from websites that don't offer RSS feeds? `html2rss` is
 
 ## Key Features
 
-- **Automatic Feed Generation:** The `auto_source` scraper intelligently finds and extracts content from websites, so you can create feeds with minimal effort.
+- **Automatic Feed Generation:** The `auto-source` scraper intelligently finds and extracts content from websites, so you can create feeds with minimal effort.
 - **Precise Content Extraction:** Use familiar CSS selectors to target the exact content you want to include in your feed.
 - **JavaScript Rendering:** Use a headless browser to render JavaScript-heavy websites and extract content that isn't available in the initial HTML.
 - **Open Source:** `html2rss` is free to use, modify, and contribute to.
diff --git a/ruby-gem/how-to/advanced-content-extraction.md b/ruby-gem/how-to/advanced-content-extraction.md
index 5ad14155..7d5845af 100644
--- a/ruby-gem/how-to/advanced-content-extraction.md
+++ b/ruby-gem/how-to/advanced-content-extraction.md
@@ -4,7 +4,6 @@ title: Advanced Content Extraction
 nav_order: 3
 parent: How-To Guides
 grand_parent: Ruby Gem
-permalink: /ruby-gem/how-to/advanced-content-extraction
 ---
 
 # Advanced Content Extraction with Selectors
diff --git a/ruby-gem/how-to/creating-custom-feeds.md b/ruby-gem/how-to/creating-custom-feeds.md
deleted file mode 100644
index b7d3057e..00000000
--- a/ruby-gem/how-to/creating-custom-feeds.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-layout: default
-title: Creating Custom Feeds
-nav_order: 1
-permalink: /web-application/how-to/creating-custom-feeds
-parent: How-To Guides
-grand_parent: Ruby Gem
----
-
-# Creating Your First Custom Feed
-
-To build your own RSS feed, you need to create a _feed config_. That _feed config_ goes into the file `feeds.yml`.
-
-Check out the [`example` feed config](https://github.com/html2rss/html2rss-web/blob/master/config/feeds.yml#L9).
-
-Please refer to [html2rss' README for a description of the feed config and its options](https://github.com/html2rss/html2rss#the-feed-config-and-its-options). html2rss-web is just a small web application that builds on html2rss.
diff --git a/ruby-gem/how-to/custom-http-requests.md b/ruby-gem/how-to/custom-http-requests.md
index 8dc26881..4885f7c7 100644
--- a/ruby-gem/how-to/custom-http-requests.md
+++ b/ruby-gem/how-to/custom-http-requests.md
@@ -4,7 +4,6 @@ title: Custom HTTP Requests
 nav_order: 4
 parent: How-To Guides
 grand_parent: Ruby Gem
-permalink: /ruby-gem/how-to/custom-http-requests
 ---
 
 # Customizing HTTP Requests
diff --git a/ruby-gem/how-to/dynamic-parameters.md b/ruby-gem/how-to/dynamic-parameters.md
index 6f83836e..b3d1f2cb 100644
--- a/ruby-gem/how-to/dynamic-parameters.md
+++ b/ruby-gem/how-to/dynamic-parameters.md
@@ -4,7 +4,6 @@ title: Dynamic Parameters
 nav_order: 5
 parent: How-To Guides
 grand_parent: Ruby Gem
-permalink: /ruby-gem/how-to/dynamic-parameters
 ---
 
 # Dynamic Parameters in URLs and Headers
diff --git a/ruby-gem/how-to/handling-dynamic-content.md b/ruby-gem/how-to/handling-dynamic-content.md
index c25ddcb2..4148a2e5 100644
--- a/ruby-gem/how-to/handling-dynamic-content.md
+++ b/ruby-gem/how-to/handling-dynamic-content.md
@@ -4,7 +4,6 @@ title: Handling Dynamic Content
 nav_order: 6
 parent: How-To Guides
 grand_parent: Ruby Gem
-permalink: /ruby-gem/how-to/handling-dynamic-content
 ---
 
 # Handling Dynamic Content and JavaScript
diff --git a/ruby-gem/how-to/index.md b/ruby-gem/how-to/index.md
index 2d312a27..f980b843 100644
--- a/ruby-gem/how-to/index.md
+++ b/ruby-gem/how-to/index.md
@@ -4,7 +4,6 @@ title: How-To Guides
 nav_order: 3
 parent: Ruby Gem
 has_children: true
-permalink: /ruby-gem/how-to
 ---
 
 # How-To Guides: Practical `html2rss` Configurations
diff --git a/ruby-gem/how-to/styling-rss-feed.md b/ruby-gem/how-to/styling-rss-feed.md
index a290ffc9..9e417211 100644
--- a/ruby-gem/how-to/styling-rss-feed.md
+++ b/ruby-gem/how-to/styling-rss-feed.md
@@ -4,7 +4,6 @@ title: Styling Your RSS Feed
 nav_order: 7
 parent: How-To Guides
 grand_parent: Ruby Gem
-permalink: /ruby-gem/how-to/styling-rss-feed
 ---
 
 # Styling Your RSS Feed
diff --git a/ruby-gem/index.md b/ruby-gem/index.md
index 206a0d58..ad7d4ae7 100644
--- a/ruby-gem/index.md
+++ b/ruby-gem/index.md
@@ -3,7 +3,6 @@ layout: default
 title: Ruby Gem
 nav_order: 3
 has_children: true
-permalink: /ruby-gem
 ---
 
 # The html2rss Ruby Gem ([GitHub Repo](https://github.com/html2rss/html2rss))
@@ -12,11 +11,23 @@ This section provides detailed documentation for the `html2rss` Ruby gem. The ge
 
 If you are looking for the easiest way to get started with `html2rss`, we recommend using the [web application]({{ '/web-application' | relative_url }}).
 
-This documentation is for developers who want to:
+This documentation is for developers who want to use the `html2rss` gem directly.
 
-- Learn how to get started with the gem: [Tutorials]({{ '/ruby-gem/tutorials' | relative_url }})
-- Find solutions to common problems: [How-To Guides]({{ '/ruby-gem/how-to' | relative_url }})
-- Look up technical details and configuration options: [Reference]({{ '/ruby-gem/reference' | relative_url }})
-- Use the `html2rss` gem directly from the command line.
-- Integrate the `html2rss` gem into their own Ruby applications.
-- Contribute to the development of `html2rss`.
+## Getting Started
+
+We recommend starting with the [Installation guide]({{ '/ruby-gem/tutorials/installation' | relative_url }}) to set up `html2rss` on your system. Once installed, proceed to our step-by-step guide to [creating your first feed]({{ '/ruby-gem/tutorials/your-first-feed' | relative_url }}).
+
+## Documentation Sections
+
+- **[Tutorials]({{ '/ruby-gem/tutorials' | relative_url }})**: Step-by-step guides to get you started.
+- **[How-To Guides]({{ '/ruby-gem/how-to' | relative_url }})**: Solutions to common problems and tasks.
+- **[Reference]({{ '/ruby-gem/reference' | relative_url }})**: Technical details and configuration options.
+
+## Advanced Topics
+
+- [**Handling Dynamic Content and JavaScript**]({{ '/ruby-gem/how-to/handling-dynamic-content' | relative_url }}): Learn how to handle JavaScript-heavy websites.
+- [**Customizing HTTP Requests**]({{ '/ruby-gem/how-to/custom-http-requests' | relative_url }}): How to send custom HTTP headers.
+- [**Dynamic Parameters in URLs and Headers**]({{ '/ruby-gem/how-to/dynamic-parameters' | relative_url }}): Use dynamic parameters in URLs and headers.
+- [**Advanced Content Extraction with Selectors**]({{ '/ruby-gem/how-to/advanced-content-extraction' | relative_url }}): Precise content extraction techniques.
+- [**Styling Your RSS Feed**]({{ '/ruby-gem/how-to/styling-rss-feed' | relative_url }}): Add stylesheets to your RSS feed.
+- [**Debugging Your Configuration**]({{ '/support/troubleshooting' | relative_url }}): Debug your feed configuration effectively.
diff --git a/ruby-gem/tutorials/installation.md b/ruby-gem/installation.md
similarity index 95%
rename from ruby-gem/tutorials/installation.md
rename to ruby-gem/installation.md
index e1b55633..101dce22 100644
--- a/ruby-gem/tutorials/installation.md
+++ b/ruby-gem/installation.md
@@ -1,10 +1,8 @@
 ---
 layout: default
 title: Installation
-nav_order: 2
-parent: Tutorials
-grand_parent: Ruby Gem
-permalink: /ruby-gem/tutorials/installation
+nav_order: 1
+parent: Ruby Gem
 ---
 
 # Installation
diff --git a/ruby-gem/reference/auto_source.md b/ruby-gem/reference/auto-source.md
similarity index 97%
rename from ruby-gem/reference/auto_source.md
rename to ruby-gem/reference/auto-source.md
index 8907908a..e1f912c3 100644
--- a/ruby-gem/reference/auto_source.md
+++ b/ruby-gem/reference/auto-source.md
@@ -4,7 +4,6 @@ title: Auto Source
 nav_order: 5
 parent: Reference
 grand_parent: Ruby Gem
-permalink: /ruby-gem/reference/auto_source
 ---
 
 # `auto_source`
diff --git a/ruby-gem/reference/channel.md b/ruby-gem/reference/channel.md
index 3ffd529d..57f5a699 100644
--- a/ruby-gem/reference/channel.md
+++ b/ruby-gem/reference/channel.md
@@ -4,7 +4,6 @@ title: Channel
 nav_order: 1
 parent: Reference
 grand_parent: Ruby Gem
-permalink: /ruby-gem/reference/channel
 ---
 
 # `channel`
diff --git a/ruby-gem/reference/cli-reference.md b/ruby-gem/reference/cli-reference.md
index 9a0478c0..1b4e29aa 100644
--- a/ruby-gem/reference/cli-reference.md
+++ b/ruby-gem/reference/cli-reference.md
@@ -4,7 +4,6 @@ title: CLI Reference
 nav_order: 7
 parent: Reference
 grand_parent: Ruby Gem
-permalink: /ruby-gem/reference/cli-reference
 ---
 
 # CLI Reference
diff --git a/ruby-gem/reference/headers.md b/ruby-gem/reference/headers.md
index 5572f271..919078b6 100644
--- a/ruby-gem/reference/headers.md
+++ b/ruby-gem/reference/headers.md
@@ -4,7 +4,6 @@ title: Headers
 nav_order: 6
 parent: Reference
 grand_parent: Ruby Gem
-permalink: /ruby-gem/reference/headers
 ---
 
 # `headers`
diff --git a/ruby-gem/reference/index.md b/ruby-gem/reference/index.md
index aa4fd456..6178cf05 100644
--- a/ruby-gem/reference/index.md
+++ b/ruby-gem/reference/index.md
@@ -14,7 +14,7 @@ This section provides a comprehensive guide to all the configuration options ava
 
 ## Configuration Topics
 
-- [**Auto Source**]({{ '/ruby-gem/reference/auto_source' | relative_url }}): The easiest way to create a feed, with minimal configuration.
+- [**Auto Source**]({{ '/ruby-gem/reference/auto-source' | relative_url }}): The easiest way to create a feed, with minimal configuration.
 - [**Channel**]({{ '/ruby-gem/reference/channel' | relative_url }}): Customize the metadata of your RSS feed.
 - [**Selectors**]({{ '/ruby-gem/reference/selectors' | relative_url }}): Use CSS selectors to extract content with precision.
 - [**Extractors**]({{ '/ruby-gem/reference/selectors/extractors' | relative_url }}): Specify how to extract information from HTML elements.
diff --git a/ruby-gem/reference/selectors/extractors.md b/ruby-gem/reference/selectors/extractors.md
index 0d438eec..a1a73905 100644
--- a/ruby-gem/reference/selectors/extractors.md
+++ b/ruby-gem/reference/selectors/extractors.md
@@ -3,7 +3,6 @@ layout: default
 title: Extractors
 parent: Selectors
 nav_order: 1
-permalink: /ruby-gem/reference/selectors/extractors
 ---
 
 # Extractors
diff --git a/ruby-gem/reference/selectors/post-processors.md b/ruby-gem/reference/selectors/post-processors.md
index 78131a57..aef39bfc 100644
--- a/ruby-gem/reference/selectors/post-processors.md
+++ b/ruby-gem/reference/selectors/post-processors.md
@@ -3,7 +3,6 @@ layout: default
 title: Post Processors
 parent: Selectors
 nav_order: 2
-permalink: /ruby-gem/reference/selectors/post-processors
 ---
 
 # Post Processors
diff --git a/ruby-gem/tutorials/getting-started.md b/ruby-gem/tutorials/getting-started.md
deleted file mode 100644
index dbcc35ae..00000000
--- a/ruby-gem/tutorials/getting-started.md
+++ /dev/null
@@ -1,42 +0,0 @@
----
-layout: default
-title: Getting Started
-nav_order: 2
-parent: Ruby Gem
-permalink: /ruby-gem/tutorials/getting-started
----
-
-# Getting Started with the html2rss Gem
-
-Welcome to the `html2rss` gem quick start guide! This section will walk you through the essential steps to get `html2rss` up and running and create your very first custom RSS feed from the command line.
-
-We've designed this guide to be as straightforward as possible, whether you're a seasoned developer or new to web scraping.
-
----
-
-## Where to Start
-
-We recommend starting with the installation guide to set up `html2rss` on your system. Once installed, proceed to our step-by-step guide to creating your first feed. It covers everything from the simplest "no-config" method to creating a custom feed with CSS selectors.
-
-[**⚙️ Start with Installation**]({{ '/ruby-gem/tutorials/installation' | relative_url }})
-
-[**🚀 Then, move to the "Your First Feed" Guide**]({{ '/ruby-gem/tutorials/your-first-feed' | relative_url }})
-
----
-
-## Automatic Generation (auto_source)
-
-For those looking for the quickest way to get started, `html2rss` offers an automatic method (`auto_source`) that intelligently scrapes a page to find content. This approach requires minimal setup and is perfect for a rapid start.
-
-[**⚡️ Learn about the "Automatic Generation" Method**]({{ '/ruby-gem/tutorials/your-first-feed/#step-1-the-no-config-method-auto' | relative_url }})
-
----
-
-## Other Topics
-
-- [**Handling Dynamic Content and JavaScript**]({{ '/ruby-gem/examples/handling-dynamic-content' | relative_url }}): Learn how to handle JavaScript-heavy websites.
-- [**Customizing HTTP Requests**]({{ '/ruby-gem/examples/custom-http-requests' | relative_url }}): How to send custom HTTP headers.
-- [**Dynamic Parameters in URLs and Headers**]({{ '/ruby-gem/examples/dynamic-parameters' | relative_url }}): Use dynamic parameters in URLs and headers.
-- [**Advanced Content Extraction with Selectors**]({{ '/ruby-gem/examples/advanced-content-extraction' | relative_url }}): Precise content extraction techniques.
-- [**Styling Your RSS Feed**]({{ '/ruby-gem/examples/styling-rss-feed' | relative_url }}): Add stylesheets to your RSS feed.
-- [**Debugging Your Configuration**]({{ '/support/troubleshooting' | relative_url }}): Debug your feed configuration effectively.
diff --git a/ruby-gem/tutorials/index.md b/ruby-gem/tutorials/index.md
new file mode 100644
index 00000000..6c33bae9
--- /dev/null
+++ b/ruby-gem/tutorials/index.md
@@ -0,0 +1,11 @@
+---
+layout: default
+title: Tutorials
+nav_order: 2
+parent: Ruby Gem
+has_children: true
+---
+
+# Tutorials
+
+This section provides step-by-step tutorials to help you get started with the `html2rss` Ruby gem.
diff --git a/ruby-gem/how-to/simple-blog-list.md b/ruby-gem/tutorials/simple-blog-list.md
similarity index 93%
rename from ruby-gem/how-to/simple-blog-list.md
rename to ruby-gem/tutorials/simple-blog-list.md
index 153853d0..f05cb2e6 100644
--- a/ruby-gem/how-to/simple-blog-list.md
+++ b/ruby-gem/tutorials/simple-blog-list.md
@@ -1,13 +1,12 @@
 ---
 layout: default
-title: Simple Blog List
-nav_order: 2
-parent: How-To Guides
+title: Scraping a Simple Blog List
+nav_order: 3
+parent: Tutorials
 grand_parent: Ruby Gem
-permalink: /ruby-gem/how-to/simple-blog-list
 ---
 
-# Example: Scraping a Simple Blog List
+# Tutorial: Scraping a Simple Blog List
 
 This example demonstrates how to create a feed from a typical blog that has a list of articles on its homepage.
 
diff --git a/ruby-gem/tutorials/your-first-feed.md b/ruby-gem/tutorials/your-first-feed.md
index 531a48f4..5a356ca6 100644
--- a/ruby-gem/tutorials/your-first-feed.md
+++ b/ruby-gem/tutorials/your-first-feed.md
@@ -1,10 +1,9 @@
 ---
 layout: default
 title: Your First Feed
-nav_order: 3
+nav_order: 2
 parent: Tutorials
 grand_parent: Ruby Gem
-permalink: /ruby-gem/tutorials/your-first-feed
 ---
 
 # Your First Feed: A Step-by-Step Guide
diff --git a/web-application/getting-started.md b/web-application/getting-started.md
new file mode 100644
index 00000000..765a0cb1
--- /dev/null
+++ b/web-application/getting-started.md
@@ -0,0 +1,28 @@
+---
+layout: default
+title: Getting Started
+nav_order: 2
+parent: Web Application
+---
+
+# Getting Started with the html2rss Web Application
+
+Welcome to the `html2rss-web` application! This guide provides a strategic overview to help you understand what the application does and how to get started.
+
+## What is html2rss-web?
+
+`html2rss-web` is a self-hosted web application that scrapes content from websites and converts it into RSS feeds. It's designed for users who want to create reliable, custom RSS feeds for sites that don't offer them.
+
+## Primary Use Cases
+
+- **Create RSS feeds** for your favorite blogs, news sites, or any website with structured content.
+- **Monitor website changes** by subscribing to the generated RSS feeds.
+- **Aggregate content** from multiple sources into your feed reader.
+
+## The Path to Your First Feed
+
+Here's the recommended path for a new user:
+
+1.  **[Installation]({{ '/web-application/installation' | relative_url }})**: Follow our step-by-step guide to set up your own instance of the application using Docker. This is the quickest and most reliable way to get started.
+
+If you're interested in more advanced topics, you can explore our **[How-To Guides]({{ '/web-application/how-to/' | relative_url }})** and the **[Reference]({{ '/web-application/reference/' | relative_url }})** section after you have your instance up and running.
diff --git a/web-application/how-to/automatic-updates.md b/web-application/how-to/automatic-updates.md
index ca4d2e6d..7385944d 100644
--- a/web-application/how-to/automatic-updates.md
+++ b/web-application/how-to/automatic-updates.md
@@ -2,7 +2,6 @@
 layout: default
 title: Automatic Updates
 nav_order: 3
-permalink: /web-application/how-to/automatic-updates
 parent: How-To Guides
 grand_parent: Web Application
 ---
@@ -11,4 +10,4 @@ grand_parent: Web Application
 
 The [watchtower](https://containrrr.dev/watchtower/) service automatically pulls running Docker images and checks for updates. If an update is available, it will automatically start the updated image with the same configuration as the running one. Please read its manual.
 
-The `docker-compose.yml` in the [Getting Started guide]({{ '/web-application/tutorials' | relative_url }}) contains a service description for watchtower.
+The `docker-compose.yml` in the [Installation Guide]({{ '/web-application/installation' | relative_url }}) contains a service description for watchtower.
diff --git a/web-application/how-to/deployment.md b/web-application/how-to/deployment.md
index 3dea1d53..8fa11b06 100644
--- a/web-application/how-to/deployment.md
+++ b/web-application/how-to/deployment.md
@@ -2,22 +2,24 @@
 layout: default
 title: Deploying to Production
 nav_order: 2
-permalink: /web-application/how-to/deployment
 parent: How-To Guides
 grand_parent: Web Application
 ---
 
 # Deploying to Production
 
-This app is published on Docker Hub and therefore easy to use with Docker.
-The `docker-compose.yml` from the [Getting Started guide]({{ '/web-application/tutorials' | relative_url }}) is a good starting point.
+If you're looking to host a personal instance of `html2rss-web`, the [Installation Guide]({{ '/web-application/installation' | relative_url }}) provides a detailed, step-by-step walkthrough.
 
-If you're going to host a public instance, _please, please, please_:
+For those who wish to host a public-facing instance, this page serves as a high-level checklist of best practices to ensure a secure and stable deployment.
 
-- Put the application behind a reverse proxy.
-- Allow outside connections only via HTTPS.
-- Have an auto-update strategy (e.g., watchtower).
-- Monitor your `/health_check.txt` endpoint.
-- [Let the world know and add your instance to the wiki](https://github.com/html2rss/html2rss-web/wiki/Instances) -- thank you!
+## Production Deployment Checklist
+
+- **Reverse Proxy**: Always put the application behind a reverse proxy. This is crucial for security and for managing incoming traffic.
+- **HTTPS**: Enforce HTTPS for all outside connections to encrypt traffic and protect user data.
+- **Auto-Updates**: Implement an auto-update strategy (e.g., using [Watchtower](https://containrrr.dev/watchtower/)) to ensure you're always running the latest, most secure version of the application.
+- **Monitoring**: Regularly monitor the `/health_check.txt` endpoint to ensure your instance is running correctly.
+- **Share Your Instance**: If you've set up a public instance, please consider [adding it to our wiki](https://github.com/html2rss/html2rss-web/wiki/Instances). This helps others discover and use the service. Thank you!
+
+## Versioning and Releases
 
 For information on the web application's versioning and release strategy, please refer to the [main Web Application overview]({{ '/web-application' | relative_url }}).
diff --git a/web-application/how-to/index.md b/web-application/how-to/index.md
index aeca5aa6..8ab7054d 100644
--- a/web-application/how-to/index.md
+++ b/web-application/how-to/index.md
@@ -1,8 +1,7 @@
 ---
 layout: default
 title: How-To Guides
-nav_order: 2
-permalink: /web-application/how-to
+nav_order: 3
 parent: Web Application
 has_children: true
 ---
diff --git a/web-application/how-to/monitoring.md b/web-application/how-to/monitoring.md
index 57679f36..483b394d 100644
--- a/web-application/how-to/monitoring.md
+++ b/web-application/how-to/monitoring.md
@@ -2,7 +2,6 @@
 layout: default
 title: Monitoring
 nav_order: 4
-permalink: /web-application/how-to/monitoring
 parent: How-To Guides
 grand_parent: Web Application
 ---
diff --git a/web-application/index.md b/web-application/index.md
index 37099e26..73fdd621 100644
--- a/web-application/index.md
+++ b/web-application/index.md
@@ -3,14 +3,17 @@ layout: default
 title: Web Application
 nav_order: 2
 has_children: true
-permalink: /web-application
 ---
 
 # html2rss-web
 
-This web application scrapes websites to build and deliver RSS 2.0 feeds. ([GitHub Repo](https://github.com/html2rss/html2rss-web))
+This web application scrapes websites to build and deliver RSS 2.0 feeds. It's a powerful tool for creating custom RSS feeds for any website.
 
-## Features
+## Get Started
+
+Ready to dive in? Our **[Getting Started guide]({{ '/web-application/getting-started' | relative_url }})** will walk you through the essential first steps, from understanding the application to installing your own instance.
+
+## Key Features
 
 - **Stable URLs:** Provides stable URLs for feeds generated by automatic sourcing.
 - **Custom Feeds:** Create your own custom feeds.
@@ -18,14 +21,3 @@ This web application scrapes websites to build and deliver RSS 2.0 feeds. ([GitH
 - **Caching:** Handles request caching and sets caching-related HTTP headers.
 
 The functionality of scraping websites and building the RSS feeds is provided by the Ruby gem [`html2rss`](https://github.com/html2rss/html2rss).
-
-## Versioning and Releases
-
-This web application is distributed in a [rolling release](https://en.wikipedia.org/wiki/Rolling_release) fashion from the `master` branch.
-
-For the latest commit passing GitHub CI/CD on the master branch, an updated Docker image will be pushed to [Docker Hub: `gilcreator/html2rss-web`](https://hub.docker.com/r/gilcreator/html2rss-web).
-The [SBOM](https://en.wikipedia.org/wiki/Software_supply_chain) is embedded in the Docker image.
-
-GitHub's @dependabot is enabled for dependency updates and they are automatically merged to the `master` branch when the CI gives the green light.
-
-If you use Docker, you should update to the latest image automatically by [setting up _watchtower_ as described]({{ '/web-application/how-to/automatic-updates' | relative_url }}).
diff --git a/web-application/installation.md b/web-application/installation.md
new file mode 100644
index 00000000..28779f11
--- /dev/null
+++ b/web-application/installation.md
@@ -0,0 +1,94 @@
+---
+layout: default
+title: Installation
+nav_order: 2
+parent: Web Application
+---
+
+# Installation
+
+This guide will walk you through setting up a personal instance of `html2rss-web` using Docker and `docker-compose`. This is the recommended way to run the application for personal use.
+
+## Prerequisites
+
+- Docker and `docker-compose` installed on your machine.
+
+See <https://docs.docker.com/get-started/>.
+
+## Step 1: Create a Project Directory
+
+First, create a directory on your machine where you'll store the configuration files for your `html2rss-web` instance.
+
+```bash
+mkdir html2rss-web;
+cd html2rss-web
+```
+
+## Step 2: Create the `docker-compose.yml` File
+
+Create a file named `docker-compose.yml` in your `html2rss-web` directory and add the following content. This setup includes the web application, a browser service for rendering JavaScript-heavy pages, and a service to automatically update the application.
+
+```yaml
+services:
+  html2rss-web:
+    image: gilcreator/html2rss-web
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:3000:3000"
+    volumes:
+      - type: bind
+        source: ./feeds.yml
+        target: /app/config/feeds.yml
+        read_only: true
+    environment:
+      RACK_ENV: production
+      HEALTH_CHECK_USERNAME: health
+      HEALTH_CHECK_PASSWORD: please-set-YOUR-OWN-veeeeeery-l0ng-aNd-h4rd-to-gue55-Passw0rd!
+      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:3001
+      BROWSERLESS_IO_API_TOKEN: 6R0W53R135510
+
+  watchtower:
+    image: containrrr/watchtower
+    restart: unless-stopped
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - "~/.docker/config.json:/config.json"
+    command: --cleanup --interval 7200
+
+  browserless:
+    image: "ghcr.io/browserless/chromium"
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:3001:3001"
+    environment:
+      PORT: 3001
+      CONCURRENT: 10
+      TOKEN: 6R0W53R135510
+```
+
+## Step 3: Create the `feeds.yml` File
+
+The application needs a file to store your feed configurations.  
+[Download the default `feeds.yml`](https://raw.githubusercontent.com/html2rss/html2rss-web/master/config/feeds.yml)
+to get started quickly:
+
+```bash
+curl https://raw.githubusercontent.com/html2rss/html2rss-web/master/config/feeds.yml -o feeds.yml
+```
+
+## Step 4: Launch the Application
+
+Now, you can start the application using `docker compose`.
+
+```bash
+docker compose up -d
+```
+
+The `-d` flag runs the containers in the background.
+
+Congratulations! Your personal `html2rss-web` instance is now running. You can access it at `http://localhost:3000`.
+
+## Next Steps
+
+- Now that your instance is running, head over to the **[Tutorials]({{ '/web-application/tutorials' | relative_url }})** to learn how to create your first feed.
+- For a more secure setup, consider putting your instance behind a reverse proxy. You can find more information in the [deployment guide]({{ '/web-application/how-to/deployment' | relative_url }}).
diff --git a/web-application/reference/index.md b/web-application/reference/index.md
index d47ecb42..a9e19dd7 100644
--- a/web-application/reference/index.md
+++ b/web-application/reference/index.md
@@ -1,8 +1,7 @@
 ---
 layout: default
 title: Reference
-nav_order: 3
-permalink: /web-application/reference
+nav_order: 4
 parent: Web Application
 has_children: true
 ---
diff --git a/web-application/tutorials/index.md b/web-application/tutorials/index.md
deleted file mode 100644
index cfca84f6..00000000
--- a/web-application/tutorials/index.md
+++ /dev/null
@@ -1,74 +0,0 @@
----
-layout: default
-title: Getting Started
-nav_order: 1
-permalink: /web-application/tutorials
-parent: Web Application
----
-
-# Getting Started with html2rss-web
-
-In this guide, you'll launch the `html2rss-web` application on your local machine. By the end, you'll have a running instance and your first live RSS feed.
-
-## Get Started in 5 Minutes
-
-The easiest way to get started is with Docker.
-
-### 1. Create Your `docker-compose.yml`
-
-Create a file named `docker-compose.yml` and paste in the following:
-
-```yaml
-services:
-  html2rss-web:
-    image: gilcreator/html2rss-web
-    ports:
-      - "3000:3000"
-    volumes:
-      - type: bind
-        source: ./feeds.yml
-        target: /app/config/feeds.yml
-        read_only: true
-    environment:
-      RACK_ENV: production
-      HEALTH_CHECK_USERNAME: health
-      HEALTH_CHECK_PASSWORD: please-set-YOUR-OWN-veeeeeery-l0ng-aNd-h4rd-to-gue55-Passw0rd!
-      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:3001
-      BROWSERLESS_IO_API_TOKEN: 6R0W53R135510
-
-  watchtower:
-    image: containrrr/watchtower
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock
-      - "~/.docker/config.json:/config.json"
-    command: --cleanup --interval 7200
-
-  browserless:
-    image: "ghcr.io/browserless/chromium"
-    ports:
-      - "3001:3001"
-    environment:
-      PORT: 3001
-      CONCURRENT: 10
-      TOKEN: 6R0W53R135510
-```
-
-### 2. Create an Empty `feeds.yml`
-
-The application needs a place to store your custom feed configurations.
-
-```bash
-touch feeds.yml
-```
-
-### 3. Launch the Application
-
-```bash
-docker compose up
-```
-
-Congratulations! The `html2rss-web` application is now running. Open your browser to `http://localhost:3000` to see it in action.
-
-### Next Up
-
-Now that you have the application running, let's [create your first custom feed]({{ '/web-application/how-to/creating-custom-feeds' | relative_url }}).

From 37655ed7cc546d3b9af4ffac477525ff7f14554f Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 2 Aug 2025 13:44:37 +0200
Subject: [PATCH 13/17] feat: update copy

---
 README.md                       |  6 +++++-
 get-involved/index.md           | 14 +++++---------
 index.md                        | 23 +++++++++++------------
 ruby-gem/index.md               | 18 +++++++-----------
 web-application/index.md        | 12 ++++++------
 web-application/installation.md |  2 +-
 6 files changed, 35 insertions(+), 40 deletions(-)

diff --git a/README.md b/README.md
index dbd4e00f..6f73f5e3 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,7 @@
 # html2rss.github.io
 
-🚧 WIP / Work in progress 🚧
+This repository hosts the documentation and website for `html2rss`, a tool for creating RSS feeds from any website.
+
+## Contributing
+
+Contributions are welcome! See our [Get Involved page](https://html2rss.github.io/get-involved) for details on discussions, reporting issues, and contributing.
diff --git a/get-involved/index.md b/get-involved/index.md
index dfde4685..cc82523b 100644
--- a/get-involved/index.md
+++ b/get-involved/index.md
@@ -7,13 +7,9 @@ nav_order: 4
 
 # Get Involved
 
-Want to participate in the `html2rss` project? Explore the options below to engage with our community and contribute to the project's growth.
+Engage with the `html2rss` project. Contribute and connect with the community.
 
-- [**The Project Roadmap**]({{ 'https://github.com/orgs/html2rss/projects/3/views/1' }}): See what's being worked on, planned, and needs attention across all `html2rss` components.
-- [**Report Bugs & Discuss Features**]({{ '/get-involved/issues-and-features' | relative_url }}): Found a bug or have a new feature idea? Learn where to report and discuss them.
-- [**Join Community Discussions**]({{ '/get-involved/discussions' | relative_url }}): Connect with other users and contributors, ask questions, and share ideas.
-- [**Contribute to html2rss**]({{ '/contributing' | relative_url }}): Ready to contribute code, documentation, or feed configurations? Find detailed guides here.
-
----
-
-We appreciate your interest in `html2rss` and look forward to your involvement!
+- [**Project Roadmap**]({{ 'https://github.com/orgs/html2rss/projects/3/views/1' }}): View current work, plans, and priorities.
+- [**Report Bugs & Discuss Features**]({{ '/get-involved/issues-and-features' | relative_url }}): Report bugs or propose features.
+- [**Join Community Discussions**]({{ '/get-involved/discussions' | relative_url }}): Connect with users and contributors.
+- [**Contribute to html2rss**]({{ '/contributing' | relative_url }}): Contribute code, documentation, or feed configurations.
diff --git a/index.md b/index.md
index 49242eb1..d8ae1254 100644
--- a/index.md
+++ b/index.md
@@ -6,29 +6,28 @@ nav_order: 1
 
 # Create RSS Feeds for Any Website
 
-Tired of missing updates from websites that don't offer RSS feeds? `html2rss` is a powerful and flexible tool that lets you create your own RSS feeds for almost any website.
-
-[**🚀 Get Started with the Web App!**]({{ '/web-application/getting-started' | relative_url }})
+`html2rss` creates RSS feeds for any website.
+[**🚀 Get Started with the Web App**]({{ '/web-application/getting-started' | relative_url }})
 
 ---
 
 ## Key Features
 
-- **Automatic Feed Generation:** The `auto-source` scraper intelligently finds and extracts content from websites, so you can create feeds with minimal effort.
-- **Precise Content Extraction:** Use familiar CSS selectors to target the exact content you want to include in your feed.
-- **JavaScript Rendering:** Use a headless browser to render JavaScript-heavy websites and extract content that isn't available in the initial HTML.
-- **Open Source:** `html2rss` is free to use, modify, and contribute to.
+- **Automatic Feed Generation:** `auto_source` intelligently extracts content, simplifying feed creation.
+- **Precise Content Extraction:** Use CSS selectors for targeted content inclusion.
+- **JavaScript Rendering:** A headless browser renders JavaScript-heavy sites for comprehensive content extraction.
+- **Open Source:** `html2rss` is free to use, modify, and contribute.
 
 ---
 
 ## The html2rss Ecosystem
 
-The `html2rss` project is more than just a single tool. It's a collection of tools that work together to provide a complete RSS solution:
+The `html2rss` project offers a complete RSS solution through a collection of integrated tools:
 
-- **[html2rss-web]({{ '/web-application' | relative_url }}):** A user-friendly web application that makes it easy to create, manage, and share RSS feeds. This is the recommended starting point for most users.
-- **[html2rss (Ruby Gem)]({{ '/ruby-gem' | relative_url }}):** The core library that powers the web application. It provides a powerful and flexible command-line interface for creating custom RSS feeds.
-- **[Feed Directory]({{ '/feed-directory' | relative_url }}):** A public listing of RSS feeds for websites of interest, powered by community-driven configurations.
+- **[html2rss-web]({{ '/web-application' | relative_url }}):** User-friendly web application to create, manage, and share RSS feeds. Recommended starting point.
+- **[html2rss (Ruby Gem)]({{ '/ruby-gem' | relative_url }}):** Core library and command-line interface for developers.
+- **[Feed Directory]({{ '/feed-directory' | relative_url }}):** Public listing of community-driven RSS feed configurations.
 
 ---
 
-Want to engage with the `html2rss` community or contribute to the project? Visit our [Get Involved]({{ '/get-involved' | relative_url }}) page for details on discussions, reporting issues, and contributing.
+Engage with the `html2rss` community or contribute. Visit our [Get Involved]({{ '/get-involved' | relative_url }}) page.
diff --git a/ruby-gem/index.md b/ruby-gem/index.md
index ad7d4ae7..bf41ea36 100644
--- a/ruby-gem/index.md
+++ b/ruby-gem/index.md
@@ -7,15 +7,11 @@ has_children: true
 
 # The html2rss Ruby Gem ([GitHub Repo](https://github.com/html2rss/html2rss))
 
-This section provides detailed documentation for the `html2rss` Ruby gem. The gem is the core library that powers the `html2rss-web` application.
-
-If you are looking for the easiest way to get started with `html2rss`, we recommend using the [web application]({{ '/web-application' | relative_url }}).
-
-This documentation is for developers who want to use the `html2rss` gem directly.
+This section documents the `html2rss` Ruby gem, the core library for `html2rss-web`. This documentation targets developers using the gem directly. For an easier start, use the [web application]({{ '/web-application' | relative_url }}).
 
 ## Getting Started
 
-We recommend starting with the [Installation guide]({{ '/ruby-gem/tutorials/installation' | relative_url }}) to set up `html2rss` on your system. Once installed, proceed to our step-by-step guide to [creating your first feed]({{ '/ruby-gem/tutorials/your-first-feed' | relative_url }}).
+Start with the [Installation guide]({{ '/ruby-gem/tutorials/installation' | relative_url }}). Then, create your [first feed]({{ '/ruby-gem/tutorials/your-first-feed' | relative_url }}).
 
 ## Documentation Sections
 
@@ -25,9 +21,9 @@ We recommend starting with the [Installation guide]({{ '/ruby-gem/tutorials/inst
 
 ## Advanced Topics
 
-- [**Handling Dynamic Content and JavaScript**]({{ '/ruby-gem/how-to/handling-dynamic-content' | relative_url }}): Learn how to handle JavaScript-heavy websites.
-- [**Customizing HTTP Requests**]({{ '/ruby-gem/how-to/custom-http-requests' | relative_url }}): How to send custom HTTP headers.
+- [**Handling Dynamic Content and JavaScript**]({{ '/ruby-gem/how-to/handling-dynamic-content' | relative_url }}): Process JavaScript-heavy websites.
+- [**Customizing HTTP Requests**]({{ '/ruby-gem/how-to/custom-http-requests' | relative_url }}): Send custom HTTP headers.
 - [**Dynamic Parameters in URLs and Headers**]({{ '/ruby-gem/how-to/dynamic-parameters' | relative_url }}): Use dynamic parameters in URLs and headers.
-- [**Advanced Content Extraction with Selectors**]({{ '/ruby-gem/how-to/advanced-content-extraction' | relative_url }}): Precise content extraction techniques.
-- [**Styling Your RSS Feed**]({{ '/ruby-gem/how-to/styling-rss-feed' | relative_url }}): Add stylesheets to your RSS feed.
-- [**Debugging Your Configuration**]({{ '/support/troubleshooting' | relative_url }}): Debug your feed configuration effectively.
+- [**Advanced Content Extraction with Selectors**]({{ '/ruby-gem/how-to/advanced-content-extraction' | relative_url }}): Advanced content extraction.
+- [**Styling Your RSS Feed**]({{ '/ruby-gem/how-to/styling-rss-feed' | relative_url }}): Add stylesheets to RSS feeds.
+- [**Debugging Your Configuration**]({{ '/support/troubleshooting' | relative_url }}): Debug feed configurations.
diff --git a/web-application/index.md b/web-application/index.md
index 73fdd621..f4e22bf4 100644
--- a/web-application/index.md
+++ b/web-application/index.md
@@ -7,17 +7,17 @@ has_children: true
 
 # html2rss-web
 
-This web application scrapes websites to build and deliver RSS 2.0 feeds. It's a powerful tool for creating custom RSS feeds for any website.
+This web application scrapes websites to build and deliver RSS 2.0 feeds. It is a powerful tool for creating custom RSS feeds.
 
 ## Get Started
 
-Ready to dive in? Our **[Getting Started guide]({{ '/web-application/getting-started' | relative_url }})** will walk you through the essential first steps, from understanding the application to installing your own instance.
+Our **[Getting Started guide]({{ '/web-application/getting-started' | relative_url }})** covers essential first steps, from understanding the application to installing your own instance.
 
 ## Key Features
 
-- **Stable URLs:** Provides stable URLs for feeds generated by automatic sourcing.
-- **Custom Feeds:** Create your own custom feeds.
-- **Feed Directory:** Comes with plenty of [feeds](https://github.com/html2rss/html2rss-configs) out of the box.
-- **Caching:** Handles request caching and sets caching-related HTTP headers.
+- **Stable URLs:** Provides stable URLs for automatically sourced feeds.
+- **Custom Feeds:** Create custom feeds.
+- **Feed Directory:** Includes many [feeds](https://github.com/html2rss/html2rss-configs) out of the box.
+- **Caching:** Handles request caching and sets HTTP headers.
 
 The functionality of scraping websites and building the RSS feeds is provided by the Ruby gem [`html2rss`](https://github.com/html2rss/html2rss).
diff --git a/web-application/installation.md b/web-application/installation.md
index 28779f11..81e48118 100644
--- a/web-application/installation.md
+++ b/web-application/installation.md
@@ -90,5 +90,5 @@ Congratulations! Your personal `html2rss-web` instance is now running. You can a
 
 ## Next Steps
 
-- Now that your instance is running, head over to the **[Tutorials]({{ '/web-application/tutorials' | relative_url }})** to learn how to create your first feed.
+- Now that your instance is running, head over to the **[How-To Guides]({{ '/web-application/how-to/' | relative_url }})** to learn how to create your first feed. We recommend starting with the [Creating Custom Feeds]({{ '/web-application/how-to/creating-custom-feeds' | relative_url }}) guide.
 - For a more secure setup, consider putting your instance behind a reverse proxy. You can find more information in the [deployment guide]({{ '/web-application/how-to/deployment' | relative_url }}).

From 6d2a855c1dddee2ae0134d2f6fa4ead0c72702d8 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 2 Aug 2025 15:25:22 +0200
Subject: [PATCH 14/17] docs: everything of gem readme

---
 get-involved/index.md                         |   4 +-
 get-involved/sponsoring.md                    |  20 +++
 ruby-gem/how-to/index.md                      |  26 +---
 ruby-gem/how-to/managing-feed-configs.md      |  63 ++++++++++
 ruby-gem/how-to/scraping-json.md              |  94 ++++++++++++++
 ruby-gem/index.md                             |  21 +---
 ruby-gem/reference/auto-source.md             |  34 ++----
 ruby-gem/reference/channel.md                 |  26 ++--
 ruby-gem/reference/headers.md                 |  44 ++-----
 ruby-gem/reference/index.md                   |  17 +--
 ruby-gem/reference/selectors.md               | 115 ++++++++++--------
 ruby-gem/reference/selectors/extractors.md    |  52 --------
 .../reference/selectors/post-processors.md    |  72 -----------
 ruby-gem/reference/strategy.md                |  72 +++--------
 ruby-gem/reference/stylesheets.md             |  61 ++--------
 support/troubleshooting.md                    | 112 +++++------------
 16 files changed, 347 insertions(+), 486 deletions(-)
 create mode 100644 get-involved/sponsoring.md
 create mode 100644 ruby-gem/how-to/managing-feed-configs.md
 create mode 100644 ruby-gem/how-to/scraping-json.md
 delete mode 100644 ruby-gem/reference/selectors/extractors.md
 delete mode 100644 ruby-gem/reference/selectors/post-processors.md

diff --git a/get-involved/index.md b/get-involved/index.md
index cc82523b..787ad020 100644
--- a/get-involved/index.md
+++ b/get-involved/index.md
@@ -1,12 +1,14 @@
 ---
 layout: default
 title: Get Involved
+nav_order: 5
 has_children: true
-nav_order: 4
 ---
 
 # Get Involved
 
+- [**Sponsoring**]({{ '/get-involved/sponsoring' | relative_url }})
+
 Engage with the `html2rss` project. Contribute and connect with the community.
 
 - [**Project Roadmap**]({{ 'https://github.com/orgs/html2rss/projects/3/views/1' }}): View current work, plans, and priorities.
diff --git a/get-involved/sponsoring.md b/get-involved/sponsoring.md
new file mode 100644
index 00000000..8b39384a
--- /dev/null
+++ b/get-involved/sponsoring.md
@@ -0,0 +1,20 @@
+---
+layout: default
+title: Sponsoring
+parent: Get Involved
+nav_order: 4
+---
+
+# Sponsoring html2rss
+
+`html2rss` is an open-source project, and its development is made possible by the support of our community. If you find `html2rss` useful, please consider sponsoring the project.
+
+## Why Sponsor?
+
+- **Ensure the project's longevity:** Your sponsorship helps to ensure that the project remains actively maintained and developed.
+- **Support new features:** Your contribution will help to fund the development of new features and improvements.
+- **Show your appreciation:** Sponsoring is a great way to show your appreciation for the project and the work that goes into it.
+
+## How to Sponsor
+
+You can sponsor the project through [GitHub Sponsors](https://github.com/sponsors/gildesmarais).
diff --git a/ruby-gem/how-to/index.md b/ruby-gem/how-to/index.md
index f980b843..9cdcd8be 100644
--- a/ruby-gem/how-to/index.md
+++ b/ruby-gem/how-to/index.md
@@ -1,31 +1,11 @@
 ---
 layout: default
 title: How-To Guides
-nav_order: 3
 parent: Ruby Gem
+nav_order: 2
 has_children: true
 ---
 
-# How-To Guides: Practical `html2rss` Configurations
+# How-To Guides
 
-This section provides a collection of ready-to-use `html2rss` configuration examples for various popular websites and common use cases. These examples demonstrate how to tackle different HTML structures and content types.
-
-Use these as a starting point, modify them to fit your specific needs, or get inspiration for building your own custom feeds.
-
----
-
-### How to Use an Example
-
-1.  **Copy the YAML:** Copy the entire YAML configuration block for the example you're interested in.
-2.  **Save as `.yml`:** Save the copied content into a file, e.g., `my-example.yml`.
-3.  **Generate the Feed:** Run `html2rss` from your terminal:
-    ```bash
-    html2rss feed my-example.yml > my-example.xml
-    ```
-4.  **Enjoy!** Open `my-example.xml` in your favorite RSS reader.
-
----
-
-### Contribute Your Own Examples!
-
-Have you created a useful `html2rss` configuration? We encourage you to share it with the community by contributing to the [`html2rss-configs`](https://github.com/html2rss/html2rss-configs) repository.
+This section provides practical examples and solutions for common tasks when using the `html2rss` gem.
diff --git a/ruby-gem/how-to/managing-feed-configs.md b/ruby-gem/how-to/managing-feed-configs.md
new file mode 100644
index 00000000..7509bb3b
--- /dev/null
+++ b/ruby-gem/how-to/managing-feed-configs.md
@@ -0,0 +1,63 @@
+---
+layout: default
+title: Managing Feed Configs
+parent: How-To Guides
+grand_parent: Ruby Gem
+nav_order: 7
+---
+
+# Managing Feed Configurations with YAML
+
+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.
+
+```yml
+# Global settings
+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"
+  "Accept": "text/html"
+
+# Feed-specific settings
+feeds:
+  my-first-feed:
+    channel:
+      url: "https://example.com/blog"
+    selectors:
+      # ...
+  my-second-feed:
+    channel:
+      url: "https://example.com/news"
+    selectors:
+      # ...
+```
+
+## Building Feeds from a YAML File
+
+### Ruby
+
+```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
+```
+
+### Command Line
+
+```sh
+# Build a specific feed
+html2rss feed feeds.yml my-first-feed
+
+# Build a feed from a single-feed YAML file
+html2rss feed single.yml
+```
diff --git a/ruby-gem/how-to/scraping-json.md b/ruby-gem/how-to/scraping-json.md
new file mode 100644
index 00000000..47c3438f
--- /dev/null
+++ b/ruby-gem/how-to/scraping-json.md
@@ -0,0 +1,94 @@
+---
+layout: default
+title: Scraping JSON Responses
+parent: How-To Guides
+grand_parent: Ruby Gem
+nav_order: 6
+---
+
+# Scraping JSON Responses
+
+When a website returns a JSON response (i.e., with a `Content-Type` of `application/json`), `html2rss` converts the JSON to XML, allowing you to use CSS selectors for data extraction.
+
+> [!NOTE]
+> The JSON response must be an Array or a Hash for the conversion to work.
+
+## JSON to XML Conversion Examples
+
+### JSON Object
+
+A JSON object like this:
+
+```json
+{
+  "data": [{ "title": "Headline", "url": "https://example.com" }]
+}
+```
+
+is converted to this XML structure:
+
+```xml
+<object>
+  <data>
+    <array>
+      <object>
+        <title>Headline</title>
+        <url>https://example.com</url>
+      </object>
+    </array>
+  </data>
+</object>
+```
+
+You would use `array > object` as your `items` selector.
+
+### JSON Array
+
+A JSON array like this:
+
+```json
+[{ "title": "Headline", "url": "https://example.com" }]
+```
+
+is converted to this XML structure:
+
+```xml
+<array>
+  <object>
+    <title>Headline</title>
+    <url>https://example.com</url>
+  </object>
+</array>
+```
+
+You would use `array > object` as your `items` selector.
+
+## Configuration Examples
+
+### Ruby
+
+```ruby
+Html2rss.feed(
+  headers: {
+    Accept: 'application/json'
+  },
+  channel: {
+    url: 'http://domainname.tld/whatever.json'
+  },
+  selectors: {
+    title: { selector: 'foo' }
+  }
+)
+```
+
+### YAML
+
+```yml
+headers:
+  Accept: application/json
+channel:
+  url: "http://domainname.tld/whatever.json"
+selectors:
+  title:
+    selector: "foo"
+```
diff --git a/ruby-gem/index.md b/ruby-gem/index.md
index bf41ea36..b208cd33 100644
--- a/ruby-gem/index.md
+++ b/ruby-gem/index.md
@@ -5,25 +5,16 @@ nav_order: 3
 has_children: true
 ---
 
-# The html2rss Ruby Gem ([GitHub Repo](https://github.com/html2rss/html2rss))
+# The html2rss Ruby Gem
 
-This section documents the `html2rss` Ruby gem, the core library for `html2rss-web`. This documentation targets developers using the gem directly. For an easier start, use the [web application]({{ '/web-application' | relative_url }}).
+This section provides comprehensive documentation for the `html2rss` Ruby gem.
 
 ## Getting Started
 
-Start with the [Installation guide]({{ '/ruby-gem/tutorials/installation' | relative_url }}). Then, create your [first feed]({{ '/ruby-gem/tutorials/your-first-feed' | relative_url }}).
+If you are new to `html2rss`, we recommend starting with the [tutorials]({{ '/ruby-gem/tutorials' | relative_url }}).
 
 ## Documentation Sections
 
-- **[Tutorials]({{ '/ruby-gem/tutorials' | relative_url }})**: Step-by-step guides to get you started.
-- **[How-To Guides]({{ '/ruby-gem/how-to' | relative_url }})**: Solutions to common problems and tasks.
-- **[Reference]({{ '/ruby-gem/reference' | relative_url }})**: Technical details and configuration options.
-
-## Advanced Topics
-
-- [**Handling Dynamic Content and JavaScript**]({{ '/ruby-gem/how-to/handling-dynamic-content' | relative_url }}): Process JavaScript-heavy websites.
-- [**Customizing HTTP Requests**]({{ '/ruby-gem/how-to/custom-http-requests' | relative_url }}): Send custom HTTP headers.
-- [**Dynamic Parameters in URLs and Headers**]({{ '/ruby-gem/how-to/dynamic-parameters' | relative_url }}): Use dynamic parameters in URLs and headers.
-- [**Advanced Content Extraction with Selectors**]({{ '/ruby-gem/how-to/advanced-content-extraction' | relative_url }}): Advanced content extraction.
-- [**Styling Your RSS Feed**]({{ '/ruby-gem/how-to/styling-rss-feed' | relative_url }}): Add stylesheets to RSS feeds.
-- [**Debugging Your Configuration**]({{ '/support/troubleshooting' | relative_url }}): Debug feed configurations.
+- **[Tutorials]({{ '/ruby-gem/tutorials' | relative_url }})**: Step-by-step guides to help you get started with `html2rss`.
+- **[How-To Guides]({{ '/ruby-gem/how-to' | relative_url }})**: Practical examples and solutions for common tasks.
+- **[Reference]({{ '/ruby-gem/reference' | relative_url }})**: Detailed information on configuration options.
diff --git a/ruby-gem/reference/auto-source.md b/ruby-gem/reference/auto-source.md
index e1f912c3..ffac4f36 100644
--- a/ruby-gem/reference/auto-source.md
+++ b/ruby-gem/reference/auto-source.md
@@ -6,11 +6,11 @@ parent: Reference
 grand_parent: Ruby Gem
 ---
 
-# `auto_source`
+# Auto Source
 
-The `auto_source` scraper is the easiest way to create a feed. It intelligently finds items on a page without requiring you to specify CSS selectors.
+The `auto_source` scraper automatically finds items on a page, so you don't have to specify CSS selectors.
 
-You can enable it in your YAML config like this:
+To enable it, add `auto_source: {}` to your configuration:
 
 ```yaml
 channel:
@@ -18,25 +18,21 @@ channel:
 auto_source: {}
 ```
 
----
-
-## How it Works
-
-The `auto_source` scraper uses a series of strategies to find content:
+## How It Works
 
-1.  **`schema`:** It looks for structured data in the form of `<script type="json/ld">` tags. Many websites use this to provide machine-readable information about their content, often following the [Schema.org](https://schema.org/) standard.
-2.  **`semantic_html`:** It searches for semantic HTML5 tags like `<article>`, `<main>`, and `<section>`. These tags are often used to define the main content of a page.
-3.  **`html`:** As a last resort, it analyzes the entire HTML structure to find frequently occurring selectors that are likely to contain the main content.
+`auto_source` uses the following strategies to find content:
 
----
+1.  **`schema`:** Parses `<script type="json/ld">` tags containing structured data (e.g., [Schema.org](https://schema.org/)).
+2.  **`semantic_html`:** Searches for semantic HTML5 tags like `<article>`, `<main>`, and `<section>`.
+3.  **`html`:** Analyzes the HTML structure to find frequently occurring selectors that are likely to contain the main content.
 
-## Fine-Tuning `auto_source`
+## Fine-Tuning
 
-You can customize the behavior of the `auto_source` scraper to improve its accuracy.
+You can customize `auto_source` to improve its accuracy.
 
 ### Scraper Options
 
-You can enable or disable specific scrapers and adjust their settings.
+Enable or disable specific scrapers and adjust their settings:
 
 ```yaml
 auto_source:
@@ -51,12 +47,9 @@ auto_source:
       use_top_selectors: 3 # default: 5
 ```
 
-- `minimum_selector_frequency`: The minimum number of times a selector must appear to be considered a candidate for the main content.
-- `use_top_selectors`: The number of top candidate selectors to consider.
-
 ### Cleanup Options
 
-You can also clean up the results to remove unwanted items.
+Remove unwanted items from the results:
 
 ```yaml
 auto_source:
@@ -64,6 +57,3 @@ auto_source:
     keep_different_domain: false # default: true
     min_words_title: 4 # default: 3
 ```
-
-- `keep_different_domain`: Whether to keep items that link to a different domain.
-- `min_words_title`: The minimum number of words a title must have to be included.
diff --git a/ruby-gem/reference/channel.md b/ruby-gem/reference/channel.md
index 57f5a699..696e5466 100644
--- a/ruby-gem/reference/channel.md
+++ b/ruby-gem/reference/channel.md
@@ -6,9 +6,9 @@ parent: Reference
 grand_parent: Ruby Gem
 ---
 
-# `channel`
+# Channel
 
-The `channel` key contains information about the RSS feed itself, such as its title, URL, and description.
+The `channel` configuration block defines the metadata for your RSS feed.
 
 ```yaml
 channel:
@@ -21,16 +21,14 @@ channel:
   time_zone: "Europe/Berlin"
 ```
 
----
-
-## Channel Options
+## Options
 
-| Attribute     | Required     | Type    | Default        | Remark                                                                                                                                  |
-| :------------ | :----------- | :------ | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
-| `url`         | **Required** | String  |                | The URL of the website to scrape.                                                                                                       |
-| `title`       | Optional     | String  | Auto-generated | The title of the RSS feed.                                                                                                              |
-| `description` | Optional     | String  | Auto-generated | Retrieved from meta description tags.                                                                                                   |
-| `author`      | Optional     | String  | Blank          | Format: `email (Name)`.                                                                                                                 |
-| `ttl`         | Optional     | Integer | Auto-generated | Time to live in minutes. `html2rss` will use the `max-age` from the response headers if available, otherwise it will default to `360`.  |
-| `language`    | Optional     | String  | Auto-generated | Determined by the `lang` attribute of the `<html>` tag.                                                                                 |
-| `time_zone`   | Optional     | String  | `'UTC'`        | The time zone to use for parsing dates. See a [list of valid time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). |
+| Attribute     | Required     | Description                                                                                                                              |
+| :------------ | :----------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
+| `url`         | **Required** | The URL of the website to scrape.                                                                                                        |
+| `title`       | Optional     | The title of the RSS feed. Defaults to the website's title.                                                                              |
+| `description` | Optional     | A description for the RSS feed. Defaults to the website's meta description.                                                              |
+| `author`      | Optional     | The author of the feed, in the format `email (Name)`.                                                                                    |
+| `ttl`         | Optional     | The "time to live" for the feed in minutes. Defaults to the `max-age` from the response headers, or `360`.                               |
+| `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). |
diff --git a/ruby-gem/reference/headers.md b/ruby-gem/reference/headers.md
index 919078b6..e55b6f11 100644
--- a/ruby-gem/reference/headers.md
+++ b/ruby-gem/reference/headers.md
@@ -6,47 +6,21 @@ parent: Reference
 grand_parent: Ruby Gem
 ---
 
-# `headers`
+# Headers
 
-The `headers` key allows you to set custom HTTP headers for your requests. This is useful for accessing protected content or interacting with APIs.
+The `headers` key allows you to set custom HTTP headers for your requests. This is useful for accessing APIs or other protected content.
+
+## Configuration
+
+You can add any number of headers to your configuration:
 
 ```yaml
 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"
   Authorization: "Bearer YOUR_TOKEN"
+  Accept: "application/json"
 ```
 
-You can also set headers for APIs that require authorization or custom headers.
-
-Dynamic parameters can be used in headers to pass values at runtime. See [Dynamic Parameters]({{ '/ruby-gem/how-to/dynamic-parameters' | relative_url }}) for more details.
-
-## Example Configuration
-
-This example demonstrates how to add custom HTTP headers to your feed request:
-
-```yaml
-channel:
-  url: https://example.com/protected-content
-  headers:
-    User-Agent: "Mozilla/5.0 (compatible; html2rss/1.0)"
-    Authorization: "Bearer your_api_token_here"
-selectors:
-  items:
-    selector: ".article"
-  title:
-    selector: "h2.title"
-  url:
-    selector: "h2.title a"
-    extractor: "href"
-  description:
-    selector: ".summary"
-```
-
-### Explanation
-
-- **`channel.headers`**: Defines custom HTTP headers to include in the request.
-- **`User-Agent`**: Some websites require a specific user agent string.
-- **`Authorization`**: Example of an API token for protected content.
-- The rest of the configuration extracts articles as usual.
+## Dynamic Parameters
 
-Use this configuration to access content that requires authentication or specific headers.
+You can also use dynamic parameters in your headers to pass values at runtime. See [Dynamic Parameters]({{ '/ruby-gem/how-to/dynamic-parameters' | relative_url }}) for more information.
diff --git a/ruby-gem/reference/index.md b/ruby-gem/reference/index.md
index 6178cf05..d5fa2e33 100644
--- a/ruby-gem/reference/index.md
+++ b/ruby-gem/reference/index.md
@@ -1,24 +1,11 @@
 ---
 layout: default
 title: Reference
-nav_order: 4
 parent: Ruby Gem
+nav_order: 3
 has_children: true
 ---
 
 # Reference
 
-While the `html2rss auto` command is a great starting point, you'll often need to create a YAML configuration file to get the perfect RSS feed. A configuration file gives you fine-grained control over every aspect of the feed generation process.
-
-This section provides a comprehensive guide to all the configuration options available in `html2rss`.
-
-## Configuration Topics
-
-- [**Auto Source**]({{ '/ruby-gem/reference/auto-source' | relative_url }}): The easiest way to create a feed, with minimal configuration.
-- [**Channel**]({{ '/ruby-gem/reference/channel' | relative_url }}): Customize the metadata of your RSS feed.
-- [**Selectors**]({{ '/ruby-gem/reference/selectors' | relative_url }}): Use CSS selectors to extract content with precision.
-- [**Extractors**]({{ '/ruby-gem/reference/selectors/extractors' | relative_url }}): Specify how to extract information from HTML elements.
-- [**Post Processors**]({{ '/ruby-gem/reference/selectors/post-processors' | relative_url }}): Manipulate the extracted data to get it just right.
-- [**Strategy**]({{ '/ruby-gem/reference/strategy' | relative_url }}): Define how html2rss fetches website content, including JavaScript rendering options.
-- [**Headers**]({{ '/ruby-gem/reference/headers' | relative_url }}): Set custom HTTP headers for requests, useful for APIs and authorization.
-- [**Stylesheets**]({{ '/ruby-gem/reference/stylesheets' | relative_url }}): Add CSS or XSLT stylesheets to style your RSS feed in browsers.
+This section provides detailed information on the various configuration options available in `html2rss`.
diff --git a/ruby-gem/reference/selectors.md b/ruby-gem/reference/selectors.md
index 3fa2fa4b..11f4d860 100644
--- a/ruby-gem/reference/selectors.md
+++ b/ruby-gem/reference/selectors.md
@@ -1,26 +1,22 @@
 ---
 layout: default
 title: Selectors
-nav_order: 6
 parent: Reference
 grand_parent: Ruby Gem
-has_children: true
-permalink: /ruby-gem/reference/selectors
+nav_order: 3
 ---
 
-# `selectors`
+# Selectors
 
-The `selectors` scraper gives you full control over the content extraction process by using CSS selectors.
+The `selectors` scraper gives you fine-grained control over content extraction using CSS selectors.
 
-To build a valid RSS 2.0 item, you need at least a `title` or a `description` in your item.
+> A valid RSS item requires at least a `title` or a `description`.
 
----
-
-## `items`
+## Basic Configuration
 
-The `items` selector is a required selector that defines the collection of HTML elements from which the RSS feed items are built.
+At a minimum, you need an `items` selector to define the list of articles and a `title` selector for the article titles.
 
-```yaml
+```yml
 channel:
   url: "https://example.com"
 selectors:
@@ -30,54 +26,75 @@ selectors:
     selector: "h1"
 ```
 
-### Item Enhancement
+## Automatic Item Enhancement
 
-`html2rss` automatically enhances each item by trying to find the `title`, `url`, and `image`. You can disable this behavior by setting `enhance: false` on the `items` selector.
+To simplify configuration, `html2rss` can automatically extract the `title`, `url`, and `image` from each item. This feature is enabled by default.
 
-```yaml
+```yml
 selectors:
   items:
     selector: ".article"
-    enhance: false
+    enhance: true # default: true
 ```
 
----
+## RSS 2.0 Selectors
+
+While you can define any named selector, only the following are used in the final RSS feed:
 
-## Selectors
+| RSS 2.0 Tag   | `html2rss` Name |
+| ------------- | --------------- |
+| `title`       | `title`         |
+| `description` | `description`   |
+| `link`        | `url`           |
+| `author`      | `author`        |
+| `category`    | `categories`    |
+| `guid`        | `guid`          |
+| `enclosure`   | `enclosure`     |
+| `pubDate`     | `published_at`  |
+| `comments`    | `comments`      |
 
-The following selectors can be used to extract content for the RSS feed:
+## Selector Options
 
-| RSS 2.0 tag   | Name in `html2rss` | Remark                                    |
-| :------------ | :----------------- | :---------------------------------------- |
-| `title`       | `title`            |                                           |
-| `description` | `description`      | Will be sanitized when it contains HTML.  |
-| `link`        | `url`              | A URL.                                    |
-| `author`      | `author`           |                                           |
-| `category`    | `categories`       | See notes below.                          |
-| `guid`        | `guid`             | Generated automatically. See notes below. |
-| `enclosure`   | `enclosure`        | See notes below.                          |
-| `pubDate`     | `published_at`     | An instance of `Time`.                    |
-| `comments`    | `comments`         | A URL.                                    |
+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.          |
+| `post_process` | A list of post-processors to apply to the value. |
 
-## Selector Options
+### Extractors
 
-Each selector can have the following attributes:
+Extractors define how to get the value from a selected element.
 
-| Name           | Value                                                                                                          |
-| :------------- | :------------------------------------------------------------------------------------------------------------- | ----------------- |
-| `selector`     | The CSS selector to select the element with the information.                                                   |
-| `extractor`    | The name of the extractor to use. See [Extractors]({{ '/ruby-gem/reference/selectors/extractors'               | relative_url }}). |
-| `post_process` | An array of post processors to apply. See [Post Processors]({{ '/ruby-gem/reference/selectors/post-processors' | relative_url }}). |
+- `text`: The inner text of the element (default).
+- `html`: The outer HTML of the element.
+- `href`: The value of the `href` attribute.
+- `attribute`: The value of a specified attribute.
+- `static`: A static value.
 
----
+### Post-Processors
 
-## Categories
+Post-processors manipulate the extracted value.
 
-The `categories` selector takes an array of selector names. The value of each of those selectors will become a `<category>` on the RSS item.
+- `gsub`: Performs a global substitution on a string.
+- `html_to_markdown`: Converts HTML to Markdown.
+- `markdown_to_html`: Converts Markdown to HTML.
+- `parse_time`: Parses a string into a `Time` object.
+- `parse_uri`: Parses a string into a `URI` object.
+- `sanitize_html`: Sanitizes HTML to prevent security vulnerabilities.
+- `substring`: Extracts a substring from a string.
+- `template`: Creates a new string from a template and other selector values.
 
-```yaml
+> Always use the `sanitize_html` post-processor for any HTML content to prevent security risks.
+
+## Advanced Usage
+
+### Categories
+
+To add categories to an item, provide a list of selector names to the `categories` selector.
+
+```yml
 selectors:
   genre:
     selector: ".genre"
@@ -88,13 +105,11 @@ selectors:
     - branch
 ```
 
----
-
-## Custom GUID
+### Custom GUID
 
-By default, `html2rss` generates a stable GUID automatically. If this is not stable, you can choose from which attributes the GUID will be built.
+To create a custom GUID for an item, provide a list of selector names to the `guid` selector.
 
-```yaml
+```yml
 selectors:
   title:
     selector: "h1"
@@ -105,13 +120,11 @@ selectors:
     - url
 ```
 
----
-
-## Enclosure
+### Enclosures
 
-An enclosure can be any file, e.g., an image, audio, or video file. The `enclosure` selector needs to return a URL of the content to enclose.
+To add an enclosure (e.g., an image, audio, or video file) to an item, use the `enclosure` selector to specify the URL of the file.
 
-```yaml
+```yml
 selectors:
   enclosure:
     selector: "audio"
diff --git a/ruby-gem/reference/selectors/extractors.md b/ruby-gem/reference/selectors/extractors.md
deleted file mode 100644
index a1a73905..00000000
--- a/ruby-gem/reference/selectors/extractors.md
+++ /dev/null
@@ -1,52 +0,0 @@
----
-layout: default
-title: Extractors
-parent: Selectors
-nav_order: 1
----
-
-# Extractors
-
-Extractors help with extracting information from the selected HTML element. You specify the extractor to use on a selector.
-
-```yaml
-selectors:
-  url:
-    selector: "a"
-    extractor: "href"
-```
-
----
-
-## Available Extractors
-
-- **`text`** (default): Returns the element's inner text.
-- **`html`**: Returns the element's outer HTML.
-- **`href`**: Returns a URL from the element's `href` attribute and corrects relative URLs to absolute ones.
-- **`attribute`**: Returns the value of an element's attribute. You must specify the `attribute` name.
-- **`static`**: Returns a configured static value. You must specify the `value`.
-
----
-
-## Extractor Examples
-
-### `attribute`
-
-```yaml
-selectors:
-  image:
-    selector: "img"
-    extractor: "attribute"
-    attribute: "src"
-```
-
-### `static`
-
-```yaml
-selectors:
-  author:
-    extractor: "static"
-    value: "John Doe"
-```
-
-For a full list of extractors and their options, please refer to the [official YARD documentation](https://www.rubydoc.info/gems/html2rss/Html2rss/Selectors/Extractors).
diff --git a/ruby-gem/reference/selectors/post-processors.md b/ruby-gem/reference/selectors/post-processors.md
deleted file mode 100644
index aef39bfc..00000000
--- a/ruby-gem/reference/selectors/post-processors.md
+++ /dev/null
@@ -1,72 +0,0 @@
----
-layout: default
-title: Post Processors
-parent: Selectors
-nav_order: 2
----
-
-# Post Processors
-
-Post processors can be used to manipulate the extracted information. You can specify one or more post processors, and they will be applied in the order they are listed.
-
-```yaml
-selectors:
-  title:
-    selector: "h1"
-    post_process:
-      - name: "gsub"
-        pattern: "foo"
-        replacement: "bar"
-      - name: "substring"
-        start: 0
-        length: 10
-```
-
----
-
-## Available Post Processors
-
-- **`gsub`**: Performs a global substitution on a string.
-- **`html_to_markdown`**: Converts HTML to Markdown.
-- **`markdown_to_html`**: Converts Markdown to HTML.
-- **`parse_time`**: Parses a string containing a time.
-- **`parse_uri`**: Parses a string as a URL.
-- **`sanitize_html`**: Strips unsafe and unneeded HTML.
-- **`substring`**: Extracts a part of a string.
-- **`template`**: Creates a new string from a template.
-
-⚠️ Always use the `sanitize_html` post processor for HTML content. Never trust the internet! ⚠️
-
----
-
-## Post Processor Examples
-
-### `gsub`
-
-```yaml
-post_process:
-  - name: "gsub"
-    pattern: "foo"
-    replacement: "bar"
-```
-
-### `template`
-
-The `template` post processor allows you to create a new string from a template, using values from other selectors.
-
-```yaml
-selectors:
-  price:
-    selector: ".price"
-  description:
-    selector: ".section"
-    post_process:
-      - name: template
-        string: |
-          # %{self}
-
-          Price: %{price}
-      - name: markdown_to_html
-```
-
-For a full list of post processors and their options, please refer to the [official YARD documentation](https://www.rubydoc.info/gems/html2rss/).
diff --git a/ruby-gem/reference/strategy.md b/ruby-gem/reference/strategy.md
index a4f6b5f5..1368be73 100644
--- a/ruby-gem/reference/strategy.md
+++ b/ruby-gem/reference/strategy.md
@@ -7,27 +7,20 @@ grand_parent: Ruby Gem
 permalink: /ruby-gem/reference/strategy
 ---
 
-# `strategy`
+# Strategy
 
-The `strategy` key defines how `html2rss` fetches the website's content.
+The `strategy` key defines how `html2rss` fetches a website's content.
 
-- **`faraday`** (default): Makes a simple HTTP request and does not execute JavaScript. It's fast and works for many websites.
-- **`browserless`**: Uses a headless Chrome browser to render the website. This is essential for JavaScript-heavy websites that build their HTML on the client side.
+- **`faraday`** (default): 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.
 
-## browserless
+## `browserless`
 
-### Requirements
+To use the `browserless` strategy, you need a running instance of [Browserless.io](https://www.browserless.io/).
 
-To use the `browserless` strategy, you need to have a [Browserless.io](https://www.browserless.io/) instance running.
+### Docker
 
-```yaml
-strategy: browserless
-```
-
-You can use _Browserless.io_ to run a headless 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:
+You can run a local Browserless.io instance using Docker:
 
 ```sh
 docker run \
@@ -38,48 +31,23 @@ docker run \
   ghcr.io/browserless/chromium
 ```
 
-### Usage examples CLI
-
-To make html2rss use your instance, specify the `browserless` strategy.
+### Configuration
 
-```sh
-# auto:
-BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000" BROWSERLESS_IO_API_TOKEN="6R0W53R135510" \
-  html2rss auto --strategy=browserless https://example.com
+Set the `strategy` to `browserless` in your feed configuration:
 
-# feed:
-BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000" BROWSERLESS_IO_API_TOKEN="6R0W53R135510" \
-  html2rss feed --strategy=browserless the_the_config.yml
+```yml
+strategy: browserless
 ```
 
-> 👉 TIP:  
-> When running locally with commands from above, you can skip setting the environment variables, as they are aligned with the default values from above example.
+### Command-Line Usage
 
-### Usage examples in feed config
+You can also specify the strategy on the command line:
 
-In your config, set `strategy: browserless`.
+```sh
+# Set environment variables for your Browserless.io instance
+BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000"
+BROWSERLESS_IO_API_TOKEN="6R0W53R135510"
 
-```yml
-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"
-channel:
-  url: https://www.imdb.com/user/ur67728460/ratings
-  ttl: 1440
-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}"
-  url:
-    selector: "a.ipc-title-link-wrapper"
-    extractor: "href"
-  user_rating:
-    selector: "[data-testid='ratingGroup--other-user-rating'] > .ipc-rating-star--rating"
+# Use the browserless strategy
+html2rss feed --strategy=browserless my_config.yml
 ```
diff --git a/ruby-gem/reference/stylesheets.md b/ruby-gem/reference/stylesheets.md
index 6d9393d3..fee9d15c 100644
--- a/ruby-gem/reference/stylesheets.md
+++ b/ruby-gem/reference/stylesheets.md
@@ -7,68 +7,25 @@ grand_parent: Ruby Gem
 permalink: /ruby-gem/reference/stylesheets
 ---
 
-# `stylesheets`
+# Stylesheets
 
-The `stylesheets` key allows you to add CSS or XSLT stylesheets to your RSS feed to improve its appearance in a web browser.
+The `stylesheets` key allows you to add CSS or XSLT stylesheets to your RSS feed, improving its appearance in web browsers.
 
-```yaml
-stylesheets:
-  - href: "/relative/base/path/to/style.xls"
-    media: "all"
-    type: "text/xsl"
-  - href: "http://example.com/rss.css"
-    media: "all"
-    type: "text/css"
-```
-
----
-
-### Explanation
+## Configuration
 
-You can add plain CSS stylesheets or XSLT (eXtensible Stylesheet Language Transformations) to style your RSS feed when viewed in a web browser.
-
-- CSS stylesheets use element selectors to apply styles.
-- XSLT allows you to use HTML templates and add JavaScript or external resources for advanced styling.
-
----
-
-### Examples
-
-#### Ruby example
-
-```ruby
-Html2rss.feed(
-  stylesheets: [
-    {
-      href: '/relative/base/path/to/style.xsl', media: :all, type: 'text/xsl'
-    },
-    {
-      href: 'http://example.com/rss.css', media: :all, type: 'text/css'
-    }
-  ],
-  channel: {},
-  selectors: {}
-)
-```
-
-#### YAML example
+You can add multiple stylesheets to your configuration:
 
 ```yaml
 stylesheets:
-  - href: "/relative/base/path/to/style.xsl"
+  - href: "/path/to/style.xls"
     media: "all"
     type: "text/xsl"
-  - href: "http://example.com/rss.css"
+  - href: "https://example.com/rss.css"
     media: "all"
     type: "text/css"
-feeds:
-  # your feed configs here
 ```
 
----
-
-### Further Reading
+## Further Reading
 
-- [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)
+- [How to Format RSS with CSS](https://www.lifewire.com/how-to-format-rss-3469302)
+- [XSLT: Extensible Stylesheet Language Transformations](https://developer.mozilla.org/en-US/docs/Web/XSLT)
diff --git a/support/troubleshooting.md b/support/troubleshooting.md
index 8fb72b5f..7a881c4e 100644
--- a/support/troubleshooting.md
+++ b/support/troubleshooting.md
@@ -4,106 +4,54 @@ title: Troubleshooting
 nav_order: 6
 ---
 
-# Troubleshooting html2rss
+# Troubleshooting
 
-Encountering issues while creating your RSS feeds? Don't worry, it happens! This section provides solutions to common problems and tips for debugging your html2rss configurations.
+This guide provides solutions to common issues encountered when using `html2rss`.
 
----
-
-## Before You Start: Essential Tools for Troubleshooting
+## Essential Tools
 
-To effectively troubleshoot `html2rss` feeds, you'll primarily use your web browser's developer tools. These tools help you inspect the structure of web pages to find the right selectors.
+Your browser's developer tools are essential for troubleshooting. Use them to inspect the HTML structure of a webpage and find the correct CSS selectors.
 
-- **How to open:** Right-click on any element on a webpage and select "Inspect" or "Inspect Element." Look for tabs like "Elements" or "Inspector."
+- **To open:** Right-click an element on a webpage and select "Inspect" or "Inspect Element."
 
----
+## Common Issues
 
-### 1. No Items in the Feed / Empty Feed
+### Empty Feeds
 
-**Possible Causes:**
+If your feed is empty, check the following:
 
-- **Incorrect `url`:** Double-check that the `url` in your configuration file is correct and accessible.
-- **Incorrect `items.selector`:** The most common reason. The CSS selector for your items might not be matching any elements on the page.
-- **Website Structure Changed:** Websites frequently update their HTML structure. Your selectors might have become outdated.
+- **URL:** Ensure the `url` in your configuration is correct and accessible.
+- **`items.selector`:** Verify that the `items.selector` matches the elements on the page.
+- **Website Changes:** Websites change their HTML structure frequently. Your selectors may be outdated.
 
-**Solutions:**
+### Missing Item Parts
 
-- **Verify URL:** Open the `url` in your browser to ensure it's correct.
-- **Inspect Element:** Use your browser's "Inspect Element" (or "Developer Tools") feature to examine the HTML structure of the target website. This allows you to see the underlying code of the webpage. Carefully identify the CSS classes or IDs of the elements you want to scrape.
-- **Test Selectors:** In your browser's developer console (usually accessible within the Developer Tools), you can test CSS selectors directly. For example, typing `document.querySelectorAll('.post-item')` and pressing Enter will show you all elements on the current page that match that specific selector. This is a quick way to verify if your selector is correct before putting it into your `html2rss` configuration.
-
----
+If parts of your items (e.g., title, link) are missing, check the following:
 
-### 2. Item Parts (Title, Link, Description) Are Missing or Incorrect
+- **Selector:** Ensure the selector for the missing part is correct and relative to the `items.selector`.
+- **Extractor:** Verify that you are using the correct `extractor` (e.g., `text`, `href`, `attribute`).
+- **Dynamic Content:** `html2rss` does not execute JavaScript. If the content is loaded dynamically, `html2rss` may not be able to see it.
 
-**Possible Causes:**
+### Date/Time Parsing Errors
 
-- **Incorrect `selector` for the part:** Similar to `items.selector`, the selector for `title`, `link`, `description`, etc., might be wrong or outdated. Remember these selectors are relative to the `items.selector` match (i.e., they look for elements _within_ each item found by `items.selector`).
-- **Incorrect `extract` attribute:** You might be trying to `extract: text` (to get the visible text) when you need `extract: href` (to get a link URL), or another attribute like `src` for an image.
-- **Content is dynamically loaded:** Some websites load content using JavaScript _after_ the initial page load. `html2rss` primarily works with the initial HTML content it receives, not content that appears later through JavaScript.
-
-**Solutions:**
-
-- **Inspect Element:** Again, use browser developer tools to find the exact selectors and attributes you need. Pay close attention to the HTML structure around the missing content.
-- **Check `extract` value:** Double-check that you're extracting the correct attribute (e.g., `text`, `href`, `src`).
-- **Dynamic Content:** If the content you're trying to scrape only appears after a delay, or after you scroll down, or after clicking something in your browser, `html2rss` might not see it. This is a limitation for purely static scraping.
-  - **How to check for dynamic content:** Load the page in your browser, then immediately disable JavaScript (often an option in developer tools or browser settings) and refresh the page. If the content disappears, it's likely dynamically loaded.
-  - **Alternatives:** Consider if the website offers an API (Application Programming Interface) or a different URL that provides the content directly in a static format (like JSON or a simpler HTML page).
-
----
+If you are having issues with date/time parsing, check the following:
 
-### 3. Date/Time Parsing Issues
+- **`time_format`:** Ensure the `time_format` in your configuration matches the date string on the website.
+- **`time_zone`:** Specify the correct `time_zone` if the website uses a specific time zone.
 
-**Possible Causes:**
+### `html2rss` Command Not Found
 
-- **Incorrect `time_format`:** The `time_format` in your configuration might not match the actual date string format on the website.
-- **Incorrect `time_zone`:** The time zone might be off, leading to incorrect timestamps.
+If you are getting a "command not found" error, try the following:
 
-**Solutions:**
-
-- **Match `time_format`:** Refer to [Ruby's `strptime` documentation](https://ruby-doc.org/core-3.0.0/Time.html#method-c-strptime) to ensure your format string (`%Y-%m-%d`, `%H:%M:%S`, etc.) accurately reflects the date string you're scraping.
-- **Specify `time_zone`:** If the website's dates are in a specific time zone, explicitly set `time_zone` (e.g., `Europe/Berlin`, `America/New_York`).
-
----
-
-### 4. html2rss Command Not Found
-
-**Possible Causes:**
-
-- **Not in PATH:** The `html2rss` executable might not be in your system's PATH. This means your operating system doesn't know where to find the `html2rss` command when you type it.
-- **Installation Issue:** `html2rss` might not have been installed correctly.
-
-**Solutions:**
-
-- **Re-install:** First, try reinstalling `html2rss` to ensure all components are in place:
-  ```bash
-  gem install html2rss
-  ```
-- **Check Your PATH (Advanced):**
-  - **What is PATH?** The `PATH` is an environment variable that tells your shell where to look for executable programs.
-  - **How to check:**
-    - **macOS/Linux:** Open your terminal and type `echo $PATH`. You'll see a list of directories separated by colons.
-    - **Windows (Command Prompt):** Open Command Prompt and type `echo %PATH%`. You'll see a list of directories separated by semicolons.
-  - **What to look for:** You need to ensure that the directory where Ruby gems install their executables is included in your `PATH`. Common locations include:
-    - `~/.rbenv/shims` (if using rbenv)
-    - `~/.rvm/bin` (if using RVM)
-    - `/usr/local/bin`
-    - A directory specific to your Ruby installation (e.g., `/usr/bin/gem`).
-  - **How to add to PATH (if missing):** This is an advanced step and varies by operating system and shell. You typically add a line to your shell's configuration file (e.g., `.bashrc`, `.zshrc`, `.profile` on macOS/Linux, or system environment variables on Windows) like:
-    ```bash
-    export PATH="/path/to/gem/bin:$PATH"
-    ```
-    After modifying, you'll need to restart your terminal or run `source ~/.bashrc` (or your respective config file). If you're unsure, searching online for "add Ruby gem bin to PATH [your operating system]" can provide detailed instructions.
-
----
-
----
+- **Re-install:** Re-install `html2rss` to ensure it is installed correctly: `gem install html2rss`.
+- **Check `PATH`:** Ensure that the directory where Ruby gems are installed is in your system's `PATH`.
 
-### Still Stuck?
+## Tips & Tricks
 
-If you've tried these solutions and are still facing issues, please don't hesitate to reach out:
+- **Mobile Redirects:** Check that the channel URL does not redirect to a mobile page with a different markup structure.
+- **`curl` and `pup`:** For static sites, use `curl` and `pup` to quickly find selectors: `curl URL | pup`.
+- **CSS Selectors:** For a comprehensive overview of CSS selectors, see the [W3C documentation](https://www.w3.org/TR/selectors-4/#overview).
 
-- **Open an Issue on GitHub:** Provide your configuration file, the target URL, and a detailed description of the problem.
-- **Check the Community:** Look for similar issues or discussions on the project's GitHub page.
+## Still Stuck?
 
-Providing as much detail as possible (your config, the exact URL, error messages, what you've tried) will help us assist you more effectively.
+If you are still having issues, please [open an issue on GitHub](https://github.com/html2rss/html2rss/issues).

From beba0423c6189c82b754a27eacaccef4df575889 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 2 Aug 2025 15:47:27 +0200
Subject: [PATCH 15/17] docs: everything of web readme

Signed-off-by: Gil Desmarais <git@desmarais.de>
---
 web-README.md                                 | 251 ++++++++++++++++++
 web-application/how-to/deployment.md          |  27 +-
 web-application/how-to/index.md               |   2 +-
 .../how-to/setup-for-development.md           |  49 ++++
 .../how-to/use-automatic-feed-generation.md   |  31 +++
 web-application/how-to/use-in-production.md   |  20 ++
 .../how-to/use-included-configs.md            |  20 ++
 .../{how-to => reference}/monitoring.md       |   8 +-
 .../reference/versioning-and-releases.md      |  18 ++
 web-application/tutorials/building-feeds.md   |  15 ++
 web-application/tutorials/index.md            |   9 +
 11 files changed, 430 insertions(+), 20 deletions(-)
 create mode 100644 web-README.md
 create mode 100644 web-application/how-to/setup-for-development.md
 create mode 100644 web-application/how-to/use-automatic-feed-generation.md
 create mode 100644 web-application/how-to/use-in-production.md
 create mode 100644 web-application/how-to/use-included-configs.md
 rename web-application/{how-to => reference}/monitoring.md (83%)
 create mode 100644 web-application/reference/versioning-and-releases.md
 create mode 100644 web-application/tutorials/building-feeds.md
 create mode 100644 web-application/tutorials/index.md

diff --git a/web-README.md b/web-README.md
new file mode 100644
index 00000000..3cf33d72
--- /dev/null
+++ b/web-README.md
@@ -0,0 +1,251 @@
+![html2rss logo](https://github.com/html2rss/html2rss/raw/master/support/logo.png)
+
+# html2rss-web
+
+This web application scrapes websites to build and deliver RSS 2.0 feeds.
+
+**Features:**
+
+- Provides stable URLs for feeds generated by automatic sourcing.
+- [Create your custom feeds](#how-to-build-your-rss-feeds)!
+- Comes with plenty of [included configs](https://github.com/html2rss/html2rss-configs) out of the box.
+- Handles request caching.
+- Sets caching-related HTTP headers.
+
+The functionality of scraping websites and building the RSS feeds is provided by the Ruby gem [`html2rss`](https://github.com/html2rss/html2rss).
+
+## Get started
+
+This application should be used with Docker. It is designed to require as little maintenance as possible. See [Versioning and Releases](#versioning-and-releases) and [consider automatic updates](#docker-automatically-keep-the-html2rss-web-image-up-to-date).
+
+### With Docker
+
+```sh
+docker run -p 3000:3000 gilcreator/html2rss-web
+```
+
+Then open <http://127.0.0.1:3000/> in your browser and click the example feed link.
+
+This is the quickest way to get started. However, it's also the option with the least flexibility: it doesn't allow you to use custom feed configs and doesn't update automatically.
+
+If you want more flexibility and automatic updates sound good to you, read on to get started _with docker compose_…
+
+### With `docker compose`
+
+Create a `docker-compose.yml` file and paste the following into it:
+
+```yaml
+services:
+  html2rss-web:
+    image: gilcreator/html2rss-web
+    ports:
+      - "3000:3000"
+    volumes:
+      - type: bind
+        source: ./feeds.yml
+        target: /app/config/feeds.yml
+        read_only: true
+    environment:
+      RACK_ENV: production
+      HEALTH_CHECK_USERNAME: health
+      HEALTH_CHECK_PASSWORD: please-set-YOUR-OWN-veeeeeery-l0ng-aNd-h4rd-to-gue55-Passw0rd!
+      # AUTO_SOURCE_ENABLED: 'true'
+      # AUTO_SOURCE_USERNAME: foobar
+      # AUTO_SOURCE_PASSWORD: A-Unique-And-Long-Password-For-Your-Own-Instance
+      ## to allow just requests originating from the local host
+      # AUTO_SOURCE_ALLOWED_ORIGINS: 127.0.0.1:3000
+      ## to allow multiple origins, seperate those via comma:
+      # AUTO_SOURCE_ALLOWED_ORIGINS: example.com,h2r.host.tld
+      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:3001
+      BROWSERLESS_IO_API_TOKEN: 6R0W53R135510
+
+  watchtower:
+    image: containrrr/watchtower
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - "~/.docker/config.json:/config.json"
+    command: --cleanup --interval 7200
+
+  browserless:
+    image: "ghcr.io/browserless/chromium"
+    ports:
+      - "3001:3001"
+    environment:
+      PORT: 3001
+      CONCURRENT: 10
+      TOKEN: 6R0W53R135510
+```
+
+Start it up with: `docker compose up`.
+
+If you have not created your `feeds.yml` yet, download [this `feeds.yml` as a blueprint](https://raw.githubusercontent.com/html2rss/html2rss-web/master/config/feeds.yml) into the directory containing the `docker-compose.yml`.
+
+## Docker: Automatically keep the html2rss-web image up-to-date
+
+The [watchtower](https://containrrr.dev/watchtower/) service automatically pulls running Docker images and checks for updates. If an update is available, it will automatically start the updated image with the same configuration as the running one. Please read its manual.
+
+The `docker-compose.yml` above contains a service description for watchtower.
+
+## How to use automatic feed generation
+
+> [!NOTE]
+> This feature is disabled by default.
+
+To enable the `auto_source` feature, comment in the env variables in the `docker-compose.yml` file from above and change the values accordingly:
+
+```yaml
+environment:
+  ## … snip ✁
+  AUTO_SOURCE_ENABLED: "true"
+  AUTO_SOURCE_USERNAME: foobar
+  AUTO_SOURCE_PASSWORD: A-Unique-And-Long-Password-For-Your-Own-Instance
+  ## to allow just requests originating from the local host
+  AUTO_SOURCE_ALLOWED_ORIGINS: 127.0.0.1:3000
+  ## to allow multiple origins, seperate those via comma:
+  # AUTO_SOURCE_ALLOWED_ORIGINS: example.com,h2r.host.tld
+  ## … snap ✃
+```
+
+Restart the container and open <http://127.0.0.1:3000/auto_source/>.
+When asked, enter your username and password.
+
+Then enter the URL of a website and click on the _Generate_ button.
+
+## How to use the included configs
+
+html2rss-web comes with many feed configs out of the box. [See the file list of all configs.](https://github.com/html2rss/html2rss-configs/tree/master/lib/html2rss/configs)
+
+To use a config from there, build the URL like this:
+
+|                          |                               |
+| ------------------------ | ----------------------------- |
+| `lib/html2rss/configs/`  | `domainname.tld/whatever.yml` |
+| Would become this URL:   |                               |
+| `http://localhost:3000/` | `domainname.tld/whatever.rss` |
+|                          | `^^^^^^^^^^^^^^^^^^^^^^^^^^^` |
+
+## How to build your RSS feeds
+
+To build your own RSS feed, you need to create a _feed config_.\
+That _feed config_ goes into the file `feeds.yml`.\
+Check out the [`example` feed config](https://github.com/html2rss/html2rss-web/blob/master/config/feeds.yml#L9).
+
+Please refer to [html2rss' README for a description of _the feed config and its options_](https://github.com/html2rss/html2rss#the-feed-config-and-its-options). html2rss-web is just a small web application that builds on html2rss.
+
+## Versioning and releases
+
+This web application is distributed in a [rolling release](https://en.wikipedia.org/wiki/Rolling_release) fashion from the `master` branch.
+
+For the latest commit passing GitHub CI/CD on the master branch, an updated Docker image will be pushed to [Docker Hub: `gilcreator/html2rss-web`](https://hub.docker.com/r/gilcreator/html2rss-web).
+The [SBOM](https://en.wikipedia.org/wiki/Software_supply_chain) is embedded in the Docker image.
+
+GitHub's @dependabot is enabled for dependency updates and they are automatically merged to the `master` branch when the CI gives the green light.
+
+If you use Docker, you should update to the latest image automatically by [setting up _watchtower_ as described](#get-started).
+
+## Use in production
+
+This app is published on Docker Hub and therefore easy to use with Docker.\
+The above `docker-compose.yml` is a good starting point.
+
+If you're going to host a public instance, _please, please, please_:
+
+- Put the application behind a reverse proxy.
+- Allow outside connections only via HTTPS.
+- Have an auto-update strategy (e.g., watchtower).
+- Monitor your `/health_check.txt` endpoint.
+- [Let the world know and add your instance to the wiki](https://github.com/html2rss/html2rss-web/wiki/Instances) -- thank you!
+
+### Supported ENV variables
+
+| Name                           | Description                        |
+| ------------------------------ | ---------------------------------- |
+| `BASE_URL`                     | default: '<http://localhost:3000>' |
+| `LOG_LEVEL`                    | default: 'warn'                    |
+| `HEALTH_CHECK_USERNAME`        | default: auto-generated on start   |
+| `HEALTH_CHECK_PASSWORD`        | default: auto-generated on start   |
+|                                |                                    |
+| `AUTO_SOURCE_ENABLED`          | default: false                     |
+| `AUTO_SOURCE_USERNAME`         | no default.                        |
+| `AUTO_SOURCE_PASSWORD`         | no default.                        |
+| `AUTO_SOURCE_ALLOWED_ORIGINS`  | no default.                        |
+|                                |                                    |
+| `PORT`                         | default: 3000                      |
+| `RACK_ENV`                     | default: 'development'             |
+| `RACK_TIMEOUT_SERVICE_TIMEOUT` | default: 15                        |
+| `WEB_CONCURRENCY`              | default: 2                         |
+| `WEB_MAX_THREADS`              | default: 5                         |
+|                                |                                    |
+| `SENTRY_DSN`                   | no default.                        |
+
+### Runtime monitoring via `GET /health_check.txt`
+
+It is recommended to set up monitoring of the `/health_check.txt` endpoint. With that, you can find out when one of _your own_ configs breaks. The endpoint uses HTTP Basic authentication.
+
+First, set the username and password via these environment variables: `HEALTH_CHECK_USERNAME` and `HEALTH_CHECK_PASSWORD`. If these are not set, html2rss-web will generate a new random username and password on _each_ start.
+
+An authenticated `GET /health_check.txt` request will respond with:
+
+- If the feeds are generatable: `success`.
+- Otherwise: the names of the broken configs.
+
+To get notified when one of your configs breaks, set up monitoring of this endpoint.
+
+[UptimeRobot's free plan](https://uptimerobot.com/) is sufficient for basic monitoring (every 5 minutes).\
+Create a monitor of type _Keyword_ with this information and make it aware of your username and password:
+
+![A screenshot showing the Keyword Monitor: a name, the instance's URL to /health_check.txt, and an interval.](docs/uptimerobot_monitor.jpg)
+
+### Application Performance Monitoring using Sentry
+
+When you specify `SENTRY_DSN` in your environment variables, the application will be setup to use Sentry.
+
+## Setup for development
+
+Check out the git repository and…
+
+### Using Docker
+
+This approach allows you to experiment without installing Ruby on your machine.
+All you need to do is install and run Docker.
+
+```sh
+# Build image from Dockerfile and name/tag it as html2rss-web:
+docker build -t html2rss-web -f Dockerfile .
+
+# 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
+
+# Open an interactive TTY with the shell `sh`:
+docker exec -ti html2rss-web-dev sh
+
+# Stop and clean up the container
+docker stop html2rss-web-dev
+docker rm html2rss-web-dev
+
+# Remove the image
+docker rmi html2rss-web
+```
+
+### Using installed Ruby
+
+If you're comfortable with installing Ruby directly on your machine, follow these instructions:
+
+1. Install Ruby `>= 3.2`
+2. `gem install bundler foreman`
+3. `bundle`
+4. `foreman start`
+
+_html2rss-web_ now listens on port **3000** for requests.
+
+## Contribute
+
+Contributions are welcome!
+
+Open a pull request with your changes,\
+open an issue, or\
+[join discussions on html2rss](https://github.com/orgs/html2rss/discussions).
diff --git a/web-application/how-to/deployment.md b/web-application/how-to/deployment.md
index 8fa11b06..d9f853f8 100644
--- a/web-application/how-to/deployment.md
+++ b/web-application/how-to/deployment.md
@@ -1,25 +1,20 @@
 ---
 layout: default
-title: Deploying to Production
-nav_order: 2
+title: Deployment
+nav_order: 4
 parent: How-To Guides
 grand_parent: Web Application
 ---
 
-# Deploying to Production
+# Deployment
 
-If you're looking to host a personal instance of `html2rss-web`, the [Installation Guide]({{ '/web-application/installation' | relative_url }}) provides a detailed, step-by-step walkthrough.
+This app is published on Docker Hub and therefore easy to use with Docker.
+The `docker-compose.yml` in the [Installation Guide]({{ '/web-application/installation' | relative_url }}) is a good starting point.
 
-For those who wish to host a public-facing instance, this page serves as a high-level checklist of best practices to ensure a secure and stable deployment.
+If you're going to host a public instance, _please, please, please_:
 
-## Production Deployment Checklist
-
-- **Reverse Proxy**: Always put the application behind a reverse proxy. This is crucial for security and for managing incoming traffic.
-- **HTTPS**: Enforce HTTPS for all outside connections to encrypt traffic and protect user data.
-- **Auto-Updates**: Implement an auto-update strategy (e.g., using [Watchtower](https://containrrr.dev/watchtower/)) to ensure you're always running the latest, most secure version of the application.
-- **Monitoring**: Regularly monitor the `/health_check.txt` endpoint to ensure your instance is running correctly.
-- **Share Your Instance**: If you've set up a public instance, please consider [adding it to our wiki](https://github.com/html2rss/html2rss-web/wiki/Instances). This helps others discover and use the service. Thank you!
-
-## Versioning and Releases
-
-For information on the web application's versioning and release strategy, please refer to the [main Web Application overview]({{ '/web-application' | relative_url }}).
+- Put the application behind a reverse proxy.
+- Allow outside connections only via HTTPS.
+- Have an auto-update strategy (e.g., watchtower).
+- Monitor your `/health_check.txt` endpoint.
+- [Let the world know and add your instance to the wiki](https://github.com/html2rss/html2rss-web/wiki/Instances) -- thank you!
diff --git a/web-application/how-to/index.md b/web-application/how-to/index.md
index 8ab7054d..d3adaa99 100644
--- a/web-application/how-to/index.md
+++ b/web-application/how-to/index.md
@@ -8,4 +8,4 @@ has_children: true
 
 # How-To Guides
 
-This section contains detailed, task-based guides for users who want to go beyond the basics.
+This section provides guides on how to perform specific tasks with html2rss-web.
diff --git a/web-application/how-to/setup-for-development.md b/web-application/how-to/setup-for-development.md
new file mode 100644
index 00000000..0209b650
--- /dev/null
+++ b/web-application/how-to/setup-for-development.md
@@ -0,0 +1,49 @@
+---
+layout: default
+title: Setup for development
+nav_order: 5
+parent: How-To Guides
+grand_parent: Web Application
+---
+
+# Setup for development
+
+Check out the git repository and…
+
+### Using Docker
+
+This approach allows you to experiment without installing Ruby on your machine.
+All you need to do is install and run Docker.
+
+```sh
+# Build image from Dockerfile and name/tag it as html2rss-web:
+docker build -t html2rss-web -f Dockerfile .
+
+# 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
+
+# Open an interactive TTY with the shell `sh`:
+docker exec -ti html2rss-web-dev sh
+
+# Stop and clean up the container
+docker stop html2rss-web-dev
+docker rm html2rss-web-dev
+
+# Remove the image
+docker rmi html2rss-web
+```
+
+### Using installed Ruby
+
+If you're comfortable with installing Ruby directly on your machine, follow these instructions:
+
+1. Install Ruby `>= 3.2`
+2. `gem install bundler foreman`
+3. `bundle`
+4. `foreman start`
+
+_html2rss-web_ now listens on port **3000** for requests.
diff --git a/web-application/how-to/use-automatic-feed-generation.md b/web-application/how-to/use-automatic-feed-generation.md
new file mode 100644
index 00000000..46d3c91c
--- /dev/null
+++ b/web-application/how-to/use-automatic-feed-generation.md
@@ -0,0 +1,31 @@
+---
+layout: default
+title: Use automatic feed generation
+nav_order: 2
+parent: How-To Guides
+grand_parent: Web Application
+---
+
+# How to use automatic feed generation
+
+> This feature is disabled by default.
+
+To enable the `auto_source` feature, comment in the env variables in the `docker-compose.yml` file from above and change the values accordingly:
+
+```yaml
+environment:
+  ## … snip ✁
+  AUTO_SOURCE_ENABLED: "true"
+  AUTO_SOURCE_USERNAME: foobar
+  AUTO_SOURCE_PASSWORD: A-Unique-And-Long-Password-For-Your-Own-Instance
+  ## to allow just requests originating from the local host
+  AUTO_SOURCE_ALLOWED_ORIGINS: 127.0.0.1:3000
+  ## to allow multiple origins, seperate those via comma:
+  # AUTO_SOURCE_ALLOWED_ORIGINS: example.com,h2r.host.tld
+  ## … snap ✃
+```
+
+Restart the container and open <http://127.0.0.1:3000/auto_source/>.
+When asked, enter your username and password.
+
+Then enter the URL of a website and click on the _Generate_ button.
diff --git a/web-application/how-to/use-in-production.md b/web-application/how-to/use-in-production.md
new file mode 100644
index 00000000..a322c41d
--- /dev/null
+++ b/web-application/how-to/use-in-production.md
@@ -0,0 +1,20 @@
+---
+layout: default
+title: Use in production
+nav_order: 4
+parent: How-To Guides
+grand_parent: Web Application
+---
+
+# Use in production
+
+This app is published on Docker Hub and therefore easy to use with Docker.
+The above `docker-compose.yml` is a good starting point.
+
+If you're going to host a public instance, _please, please, please_:
+
+- Put the application behind a reverse proxy.
+- Allow outside connections only via HTTPS.
+- Have an auto-update strategy (e.g., watchtower).
+- Monitor your `/health_check.txt` endpoint.
+- [Let the world know and add your instance to the wiki](https://github.com/html2rss/html2rss-web/wiki/Instances) -- thank you!
diff --git a/web-application/how-to/use-included-configs.md b/web-application/how-to/use-included-configs.md
new file mode 100644
index 00000000..c24bd1fd
--- /dev/null
+++ b/web-application/how-to/use-included-configs.md
@@ -0,0 +1,20 @@
+---
+layout: default
+title: Use the included configs
+parent: How-To Guides
+grand_parent: Web Application
+nav_order: 3
+---
+
+# How to use the included configs
+
+html2rss-web comes with many feed configs out of the box. [See the file list of all configs.](https://github.com/html2rss/html2rss-configs/tree/master/lib/html2rss/configs)
+
+To use a config from there, build the URL like this:
+
+|                          |                               |
+| ------------------------ | ----------------------------- |
+| `lib/html2rss/configs/`  | `domainname.tld/whatever.yml` |
+| Would become this URL:   |                               |
+| `http://localhost:3000/` | `domainname.tld/whatever.rss` |
+|                          | `^^^^^^^^^^^^^^^^^^^^^^^^^^^` |
diff --git a/web-application/how-to/monitoring.md b/web-application/reference/monitoring.md
similarity index 83%
rename from web-application/how-to/monitoring.md
rename to web-application/reference/monitoring.md
index 483b394d..d328aa26 100644
--- a/web-application/how-to/monitoring.md
+++ b/web-application/reference/monitoring.md
@@ -1,9 +1,9 @@
 ---
 layout: default
 title: Monitoring
-nav_order: 4
-parent: How-To Guides
+parent: Reference
 grand_parent: Web Application
+nav_order: 3
 ---
 
 # Monitoring
@@ -22,7 +22,9 @@ An authenticated `GET /health_check.txt` request will respond with:
 To get notified when one of your configs breaks, set up monitoring of this endpoint.
 
 [UptimeRobot's free plan](https://uptimerobot.com/) is sufficient for basic monitoring (every 5 minutes).
-Create a monitor of type _Keyword_ with this information and make it aware of your username and password.
+Create a monitor of type _Keyword_ with this information and make it aware of your username and password:
+
+![A screenshot showing the Keyword Monitor: a name, the instance's URL to /health_check.txt, and an interval.](docs/uptimerobot_monitor.jpg)
 
 ## Application Performance Monitoring using Sentry
 
diff --git a/web-application/reference/versioning-and-releases.md b/web-application/reference/versioning-and-releases.md
new file mode 100644
index 00000000..ce47eaaf
--- /dev/null
+++ b/web-application/reference/versioning-and-releases.md
@@ -0,0 +1,18 @@
+---
+layout: default
+title: Versioning and releases
+parent: Reference
+grand_parent: Web Application
+nav_order: 5
+---
+
+# Versioning and releases
+
+This web application is distributed in a [rolling release](https://en.wikipedia.org/wiki/Rolling_release) fashion from the `master` branch.
+
+For the latest commit passing GitHub CI/CD on the master branch, an updated Docker image will be pushed to [Docker Hub: `gilcreator/html2rss-web`](https://hub.docker.com/r/gilcreator/html2rss-web).
+The [SBOM](https://en.wikipedia.org/wiki/Software_supply_chain) is embedded in the Docker image.
+
+GitHub's @dependabot is enabled for dependency updates and they are automatically merged to the `master` branch when the CI gives the green light.
+
+If you use Docker, you should update to the latest image automatically by [setting up _watchtower_ as described]({{ '/web-application/how-to/automatic-updates' | relative_url }}).
diff --git a/web-application/tutorials/building-feeds.md b/web-application/tutorials/building-feeds.md
new file mode 100644
index 00000000..64e28b98
--- /dev/null
+++ b/web-application/tutorials/building-feeds.md
@@ -0,0 +1,15 @@
+---
+layout: default
+title: Building your RSS feeds
+nav_order: 1
+parent: Tutorials
+grand_parent: Web Application
+---
+
+# How to build your RSS feeds
+
+To build your own RSS feed, you need to create a _feed config_.
+That _feed config_ goes into the file `feeds.yml`.
+Check out the [`example` feed config](https://github.com/html2rss/html2rss-web/blob/master/config/feeds.yml#L9).
+
+Please refer to [html2rss' README for a description of _the feed config and its options_](https://github.com/html2rss/html2rss#the-feed-config-and-its-options). html2rss-web is just a small web application that builds on html2rss.
diff --git a/web-application/tutorials/index.md b/web-application/tutorials/index.md
new file mode 100644
index 00000000..788baee0
--- /dev/null
+++ b/web-application/tutorials/index.md
@@ -0,0 +1,9 @@
+---
+layout: default
+title: Tutorials
+parent: Web Application
+nav_order: 3
+has_children: true
+---
+
+# Tutorials

From 0c89e8a4a7a1d38f360dfbcde898cc2f95cde804 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <gildesmarais@users.noreply.github.com>
Date: Sat, 2 Aug 2025 16:02:48 +0200
Subject: [PATCH 16/17] Update feed-directory/index.html

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: Gil Desmarais <git@desmarais.de>
---
 feed-directory/index.html | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/feed-directory/index.html b/feed-directory/index.html
index 125c3f51..2aeef3a8 100644
--- a/feed-directory/index.html
+++ b/feed-directory/index.html
@@ -215,6 +215,8 @@ <h2 class="fs-6">Contribute to the Directory</h2>
   defer
 ></script>
 <script
-  src="https://cdn.jsdelivr.net/npm/alpinejs@3.14.1/dist/cdn.min.js"
+  src="https://cdn.jsdelivr.net/npm/alpinejs@3.14.9/dist/cdn.min.js"
+  integrity="sha256-PtHu0lJIiSHfZeNj1nFd6wTX+Squ255SGZ/fc8seCtM="
+  crossorigin="anonymous"
   defer
 ></script>

From cb0869c7bb37780317548a84f196b29eb4483627 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 2 Aug 2025 16:10:46 +0200
Subject: [PATCH 17/17] chore(deps): update npm packages

---
 package.json |   8 +-
 yarn.lock    | 365 ++++++++++++++++++++++++---------------------------
 2 files changed, 174 insertions(+), 199 deletions(-)

diff --git a/package.json b/package.json
index 8733ed55..b942234a 100644
--- a/package.json
+++ b/package.json
@@ -10,12 +10,12 @@
     "lintfix:prettier": "prettier --write ."
   },
   "devDependencies": {
-    "prettier": "3.3.3",
-    "stylelint": "16.22.0",
+    "prettier": "3.6.2",
+    "stylelint": "16.23.0",
     "stylelint-config-recess-order": "7.1.0",
-    "stylelint-order": "6.0.4",
+    "stylelint-order": "7.0.0",
     "stylelint-config-recommended-scss": "15.0.1",
     "stylelint-scss": "6.12.1"
   },
-  "packageManager": "yarn@1.22.19+sha1.4ba7fc5c6e704fce2066ecbfb0b0d8976fe62447"
+  "packageManager": "yarn@1.22.22"
 }
diff --git a/yarn.lock b/yarn.lock
index d5ea367a..6081eba4 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -4,19 +4,19 @@
 
 "@babel/code-frame@^7.0.0":
   version "7.10.1"
-  resolved "https://registry.yarnpkg.com/@babel/code-frame/-/code-frame-7.10.1.tgz#d5481c5095daa1c57e16e54c6f9198443afb49ff"
+  resolved "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.10.1.tgz"
   integrity sha512-IGhtTmpjGbYzcEDOw7DcQtbQSXcG9ftmAXtWTu9V936vDye4xjjekktFAtgZsWpzTj/X01jocB46mTywm/4SZw==
   dependencies:
     "@babel/highlight" "^7.10.1"
 
 "@babel/helper-validator-identifier@^7.10.1":
   version "7.10.1"
-  resolved "https://registry.yarnpkg.com/@babel/helper-validator-identifier/-/helper-validator-identifier-7.10.1.tgz#5770b0c1a826c4f53f5ede5e153163e0318e94b5"
+  resolved "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.10.1.tgz"
   integrity sha512-5vW/JXLALhczRCWP0PnFDMCJAchlBvM7f4uk/jXritBnIa6E1KmqmtrS3yn1LAnxFBypQ3eneLuXjsnfQsgILw==
 
 "@babel/highlight@^7.10.1":
   version "7.10.1"
-  resolved "https://registry.yarnpkg.com/@babel/highlight/-/highlight-7.10.1.tgz#841d098ba613ba1a427a2b383d79e35552c38ae0"
+  resolved "https://registry.npmjs.org/@babel/highlight/-/highlight-7.10.1.tgz"
   integrity sha512-8rMof+gVP8mxYZApLF/JgNDAkdKa+aJt3ZYxF8z6+j/hpeXL7iMsKCPHa2jNMHu/qqBwzQF4OHNoYi8dMA/rYg==
   dependencies:
     "@babel/helper-validator-identifier" "^7.10.1"
@@ -25,39 +25,37 @@
 
 "@csstools/css-parser-algorithms@^3.0.5":
   version "3.0.5"
-  resolved "https://registry.yarnpkg.com/@csstools/css-parser-algorithms/-/css-parser-algorithms-3.0.5.tgz#5755370a9a29abaec5515b43c8b3f2cf9c2e3076"
+  resolved "https://registry.npmjs.org/@csstools/css-parser-algorithms/-/css-parser-algorithms-3.0.5.tgz"
   integrity sha512-DaDeUkXZKjdGhgYaHNJTV9pV7Y9B3b644jCLs9Upc3VeNGg6LWARAT6O+Q+/COo+2gg/bM5rhpMAtf70WqfBdQ==
 
 "@csstools/css-tokenizer@^3.0.4":
   version "3.0.4"
-  resolved "https://registry.yarnpkg.com/@csstools/css-tokenizer/-/css-tokenizer-3.0.4.tgz#333fedabc3fd1a8e5d0100013731cf19e6a8c5d3"
+  resolved "https://registry.npmjs.org/@csstools/css-tokenizer/-/css-tokenizer-3.0.4.tgz"
   integrity sha512-Vd/9EVDiu6PPJt9yAh6roZP6El1xHrdvIVGjyBsHR0RYwNHgL7FJPyIIW4fANJNG6FtyZfvlRPpFI4ZM/lubvw==
 
 "@csstools/media-query-list-parser@^4.0.3":
   version "4.0.3"
-  resolved "https://registry.yarnpkg.com/@csstools/media-query-list-parser/-/media-query-list-parser-4.0.3.tgz#7aec77bcb89c2da80ef207e73f474ef9e1b3cdf1"
+  resolved "https://registry.npmjs.org/@csstools/media-query-list-parser/-/media-query-list-parser-4.0.3.tgz"
   integrity sha512-HAYH7d3TLRHDOUQK4mZKf9k9Ph/m8Akstg66ywKR4SFAigjs3yBiUeZtFxywiTm5moZMAp/5W/ZuFnNXXYLuuQ==
 
 "@csstools/selector-specificity@^5.0.0":
   version "5.0.0"
-  resolved "https://registry.yarnpkg.com/@csstools/selector-specificity/-/selector-specificity-5.0.0.tgz#037817b574262134cabd68fc4ec1a454f168407b"
+  resolved "https://registry.npmjs.org/@csstools/selector-specificity/-/selector-specificity-5.0.0.tgz"
   integrity sha512-PCqQV3c4CoVm3kdPhyeZ07VmBRdH2EpMFA/pd9OASpOEC3aXNGoqPDAZ80D0cLpMBxnmk0+yNhGsEx31hq7Gtw==
 
 "@dual-bundle/import-meta-resolve@^4.1.0":
   version "4.1.0"
-  resolved "https://registry.yarnpkg.com/@dual-bundle/import-meta-resolve/-/import-meta-resolve-4.1.0.tgz#519c1549b0e147759e7825701ecffd25e5819f7b"
+  resolved "https://registry.npmjs.org/@dual-bundle/import-meta-resolve/-/import-meta-resolve-4.1.0.tgz"
   integrity sha512-+nxncfwHM5SgAtrVzgpzJOI1ol0PkumhVo469KCf9lUi21IGcY90G98VuHm9VRrUypmAzawAHO9bs6hqeADaVg==
 
-"@keyv/serialize@^1.0.3":
-  version "1.0.3"
-  resolved "https://registry.yarnpkg.com/@keyv/serialize/-/serialize-1.0.3.tgz#e0fe3710e2a379cb0490cd41e5a5ffa2bab58bf6"
-  integrity sha512-qnEovoOp5Np2JDGonIDL6Ayihw0RhnRh6vxPuHo4RDn1UOzwEo4AeIfpL6UGIrsceWrCMiVPgwRjbHu4vYFc3g==
-  dependencies:
-    buffer "^6.0.3"
+"@keyv/serialize@^1.1.0":
+  version "1.1.0"
+  resolved "https://registry.npmjs.org/@keyv/serialize/-/serialize-1.1.0.tgz"
+  integrity sha512-RlDgexML7Z63Q8BSaqhXdCYNBy/JQnqYIwxofUrNLGCblOMHp+xux2Q8nLMLlPpgHQPoU0Do8Z6btCpRBEqZ8g==
 
 "@nodelib/fs.scandir@2.1.3":
   version "2.1.3"
-  resolved "https://registry.yarnpkg.com/@nodelib/fs.scandir/-/fs.scandir-2.1.3.tgz#3a582bdb53804c6ba6d146579c46e52130cf4a3b"
+  resolved "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.3.tgz"
   integrity sha512-eGmwYQn3gxo4r7jdQnkrrN6bY478C3P+a/y72IJukF8LjB6ZHeB3c+Ehacj3sYeSmUXGlnA67/PmbM9CVwL7Dw==
   dependencies:
     "@nodelib/fs.stat" "2.0.3"
@@ -65,12 +63,12 @@
 
 "@nodelib/fs.stat@2.0.3", "@nodelib/fs.stat@^2.0.2":
   version "2.0.3"
-  resolved "https://registry.yarnpkg.com/@nodelib/fs.stat/-/fs.stat-2.0.3.tgz#34dc5f4cabbc720f4e60f75a747e7ecd6c175bd3"
+  resolved "https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.3.tgz"
   integrity sha512-bQBFruR2TAwoevBEd/NWMoAAtNGzTRgdrqnYCc7dhzfoNvqPzLyqlEQnzZ3kVnNrSp25iyxE00/3h2fqGAGArA==
 
 "@nodelib/fs.walk@^1.2.3":
   version "1.2.4"
-  resolved "https://registry.yarnpkg.com/@nodelib/fs.walk/-/fs.walk-1.2.4.tgz#011b9202a70a6366e436ca5c065844528ab04976"
+  resolved "https://registry.npmjs.org/@nodelib/fs.walk/-/fs.walk-1.2.4.tgz"
   integrity sha512-1V9XOY4rDW0rehzbrcqAmHnz8e7SKvX27gh8Gt2WgB0+pdzdiLV83p72kZPU+jvMbS1qU5mauP2iOvO8rhmurQ==
   dependencies:
     "@nodelib/fs.scandir" "2.1.3"
@@ -78,7 +76,7 @@
 
 ajv@^8.0.1:
   version "8.3.0"
-  resolved "https://registry.yarnpkg.com/ajv/-/ajv-8.3.0.tgz#25ee7348e32cdc4a1dbb38256bf6bdc451dd577c"
+  resolved "https://registry.npmjs.org/ajv/-/ajv-8.3.0.tgz"
   integrity sha512-RYE7B5An83d7eWnDR8kbdaIFqmKCNsP16ay1hDbJEU+sa0e3H9SebskCt0Uufem6cfAVu7Col6ubcn/W+Sm8/Q==
   dependencies:
     fast-deep-equal "^3.1.1"
@@ -88,79 +86,66 @@ ajv@^8.0.1:
 
 ansi-regex@^5.0.1:
   version "5.0.1"
-  resolved "https://registry.yarnpkg.com/ansi-regex/-/ansi-regex-5.0.1.tgz#082cb2c89c9fe8659a311a53bd6a4dc5301db304"
+  resolved "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz"
   integrity sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==
 
 ansi-styles@^3.2.1:
   version "3.2.1"
-  resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-3.2.1.tgz#41fbb20243e50b12be0f04b8dedbf07520ce841d"
+  resolved "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz"
   integrity sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==
   dependencies:
     color-convert "^1.9.0"
 
 ansi-styles@^4.0.0:
   version "4.3.0"
-  resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-4.3.0.tgz#edd803628ae71c04c85ae7a0906edad34b648937"
+  resolved "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz"
   integrity sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==
   dependencies:
     color-convert "^2.0.1"
 
 argparse@^2.0.1:
   version "2.0.1"
-  resolved "https://registry.yarnpkg.com/argparse/-/argparse-2.0.1.tgz#246f50f3ca78a3240f6c997e8a9bd1eac49e4b38"
+  resolved "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz"
   integrity sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==
 
 array-union@^2.1.0:
   version "2.1.0"
-  resolved "https://registry.yarnpkg.com/array-union/-/array-union-2.1.0.tgz#b798420adbeb1de828d84acd8a2e23d3efe85e8d"
+  resolved "https://registry.npmjs.org/array-union/-/array-union-2.1.0.tgz"
   integrity sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw==
 
 astral-regex@^2.0.0:
   version "2.0.0"
-  resolved "https://registry.yarnpkg.com/astral-regex/-/astral-regex-2.0.0.tgz#483143c567aeed4785759c0865786dc77d7d2e31"
+  resolved "https://registry.npmjs.org/astral-regex/-/astral-regex-2.0.0.tgz"
   integrity sha512-Z7tMw1ytTXt5jqMcOP+OQteU1VuNK9Y02uuJtKQ1Sv69jXQKKg5cibLwGJow8yzZP+eAc18EmLGPal0bp36rvQ==
 
 balanced-match@^2.0.0:
   version "2.0.0"
-  resolved "https://registry.yarnpkg.com/balanced-match/-/balanced-match-2.0.0.tgz#dc70f920d78db8b858535795867bf48f820633d9"
+  resolved "https://registry.npmjs.org/balanced-match/-/balanced-match-2.0.0.tgz"
   integrity sha512-1ugUSr8BHXRnK23KfuYS+gVMC3LB8QGH9W1iGtDPsNWoQbgtXSExkBu2aDR4epiGWZOjZsj6lDl/N/AqqTC3UA==
 
-base64-js@^1.3.1:
-  version "1.5.1"
-  resolved "https://registry.yarnpkg.com/base64-js/-/base64-js-1.5.1.tgz#1b1b440160a5bf7ad40b650f095963481903930a"
-  integrity sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==
-
 braces@^3.0.3:
   version "3.0.3"
-  resolved "https://registry.yarnpkg.com/braces/-/braces-3.0.3.tgz#490332f40919452272d55a8480adc0c441358789"
+  resolved "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz"
   integrity sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==
   dependencies:
     fill-range "^7.1.1"
 
-buffer@^6.0.3:
-  version "6.0.3"
-  resolved "https://registry.yarnpkg.com/buffer/-/buffer-6.0.3.tgz#2ace578459cc8fbe2a70aaa8f52ee63b6a74c6c6"
-  integrity sha512-FTiCpNxtwiZZHEZbcbTIcZjERVICn9yq/pDFkTl95/AxzD1naBctN7YO68riM/gLSDY7sdrMby8hofADYuuqOA==
-  dependencies:
-    base64-js "^1.3.1"
-    ieee754 "^1.2.1"
-
-cacheable@^1.10.0:
-  version "1.10.0"
-  resolved "https://registry.yarnpkg.com/cacheable/-/cacheable-1.10.0.tgz#844dc3bc299344af373b728d9f4f0906ee67c1c9"
-  integrity sha512-SSgQTAnhd7WlJXnGlIi4jJJOiHzgnM5wRMEPaXAU4kECTAMpBoYKoZ9i5zHmclIEZbxcu3j7yY/CF8DTmwIsHg==
+cacheable@^1.10.3:
+  version "1.10.3"
+  resolved "https://registry.npmjs.org/cacheable/-/cacheable-1.10.3.tgz"
+  integrity sha512-M6p10iJ/VT0wT7TLIGUnm958oVrU2cUK8pQAVU21Zu7h8rbk/PeRtRWrvHJBql97Bhzk3g1N6+2VKC+Rjxna9Q==
   dependencies:
-    hookified "^1.8.2"
-    keyv "^5.3.3"
+    hookified "^1.10.0"
+    keyv "^5.4.0"
 
 callsites@^3.0.0:
   version "3.1.0"
-  resolved "https://registry.yarnpkg.com/callsites/-/callsites-3.1.0.tgz#b3630abd8943432f54b3f0519238e33cd7df2f73"
+  resolved "https://registry.npmjs.org/callsites/-/callsites-3.1.0.tgz"
   integrity sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==
 
 chalk@^2.0.0:
   version "2.4.2"
-  resolved "https://registry.yarnpkg.com/chalk/-/chalk-2.4.2.tgz#cd42541677a54333cf541a49108c1432b44c9424"
+  resolved "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz"
   integrity sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==
   dependencies:
     ansi-styles "^3.2.1"
@@ -169,36 +154,36 @@ chalk@^2.0.0:
 
 color-convert@^1.9.0:
   version "1.9.3"
-  resolved "https://registry.yarnpkg.com/color-convert/-/color-convert-1.9.3.tgz#bb71850690e1f136567de629d2d5471deda4c1e8"
+  resolved "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz"
   integrity sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==
   dependencies:
     color-name "1.1.3"
 
 color-convert@^2.0.1:
   version "2.0.1"
-  resolved "https://registry.yarnpkg.com/color-convert/-/color-convert-2.0.1.tgz#72d3a68d598c9bdb3af2ad1e84f21d896abd4de3"
+  resolved "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz"
   integrity sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==
   dependencies:
     color-name "~1.1.4"
 
 color-name@1.1.3:
   version "1.1.3"
-  resolved "https://registry.yarnpkg.com/color-name/-/color-name-1.1.3.tgz#a7d0558bd89c42f795dd42328f740831ca53bc25"
+  resolved "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz"
   integrity sha1-p9BVi9icQveV3UIyj3QIMcpTvCU=
 
 color-name@~1.1.4:
   version "1.1.4"
-  resolved "https://registry.yarnpkg.com/color-name/-/color-name-1.1.4.tgz#c2a09a87acbde69543de6f63fa3995c826c536a2"
+  resolved "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz"
   integrity sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==
 
 colord@^2.9.3:
   version "2.9.3"
-  resolved "https://registry.yarnpkg.com/colord/-/colord-2.9.3.tgz#4f8ce919de456f1d5c1c368c307fe20f3e59fb43"
+  resolved "https://registry.npmjs.org/colord/-/colord-2.9.3.tgz"
   integrity sha512-jeC1axXpnb0/2nn/Y1LPuLdgXBLH7aDcHu4KEKfqw3CUhX7ZpfBSlPKyqXE6btIgEzfWtrX3/tyBCaCvXvMkOw==
 
 cosmiconfig@^9.0.0:
   version "9.0.0"
-  resolved "https://registry.yarnpkg.com/cosmiconfig/-/cosmiconfig-9.0.0.tgz#34c3fc58287b915f3ae905ab6dc3de258b55ad9d"
+  resolved "https://registry.npmjs.org/cosmiconfig/-/cosmiconfig-9.0.0.tgz"
   integrity sha512-itvL5h8RETACmOTFc4UfIyB2RfEHi71Ax6E/PivVxq9NseKbOWpeyHEOIbmAw1rs8Ak0VursQNww7lf7YtUwzg==
   dependencies:
     env-paths "^2.2.1"
@@ -208,12 +193,12 @@ cosmiconfig@^9.0.0:
 
 css-functions-list@^3.2.3:
   version "3.2.3"
-  resolved "https://registry.yarnpkg.com/css-functions-list/-/css-functions-list-3.2.3.tgz#95652b0c24f0f59b291a9fc386041a19d4f40dbe"
+  resolved "https://registry.npmjs.org/css-functions-list/-/css-functions-list-3.2.3.tgz"
   integrity sha512-IQOkD3hbR5KrN93MtcYuad6YPuTSUhntLHDuLEbFWE+ff2/XSZNdZG+LcbbIW5AXKg/WFIfYItIzVoHngHXZzA==
 
 css-tree@^3.0.1, css-tree@^3.1.0:
   version "3.1.0"
-  resolved "https://registry.yarnpkg.com/css-tree/-/css-tree-3.1.0.tgz#7aabc035f4e66b5c86f54570d55e05b1346eb0fd"
+  resolved "https://registry.npmjs.org/css-tree/-/css-tree-3.1.0.tgz"
   integrity sha512-0eW44TGN5SQXU1mWSkKwFstI/22X2bG1nYzZTYMAWjylYURhse752YgbE4Cx46AC+bAvI+/dYTPRk1LqSUnu6w==
   dependencies:
     mdn-data "2.12.2"
@@ -221,53 +206,53 @@ css-tree@^3.0.1, css-tree@^3.1.0:
 
 cssesc@^3.0.0:
   version "3.0.0"
-  resolved "https://registry.yarnpkg.com/cssesc/-/cssesc-3.0.0.tgz#37741919903b868565e1c09ea747445cd18983ee"
+  resolved "https://registry.npmjs.org/cssesc/-/cssesc-3.0.0.tgz"
   integrity sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==
 
 debug@^4.4.1:
   version "4.4.1"
-  resolved "https://registry.yarnpkg.com/debug/-/debug-4.4.1.tgz#e5a8bc6cbc4c6cd3e64308b0693a3d4fa550189b"
+  resolved "https://registry.npmjs.org/debug/-/debug-4.4.1.tgz"
   integrity sha512-KcKCqiftBJcZr++7ykoDIEwSa3XWowTfNPo92BYxjXiyYEVrUQh2aLyhxBCwww+heortUFxEJYcRzosstTEBYQ==
   dependencies:
     ms "^2.1.3"
 
 dir-glob@^3.0.1:
   version "3.0.1"
-  resolved "https://registry.yarnpkg.com/dir-glob/-/dir-glob-3.0.1.tgz#56dbf73d992a4a93ba1584f4534063fd2e41717f"
+  resolved "https://registry.npmjs.org/dir-glob/-/dir-glob-3.0.1.tgz"
   integrity sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==
   dependencies:
     path-type "^4.0.0"
 
 emoji-regex@^8.0.0:
   version "8.0.0"
-  resolved "https://registry.yarnpkg.com/emoji-regex/-/emoji-regex-8.0.0.tgz#e818fd69ce5ccfcb404594f842963bf53164cc37"
+  resolved "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz"
   integrity sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==
 
 env-paths@^2.2.1:
   version "2.2.1"
-  resolved "https://registry.yarnpkg.com/env-paths/-/env-paths-2.2.1.tgz#420399d416ce1fbe9bc0a07c62fa68d67fd0f8f2"
+  resolved "https://registry.npmjs.org/env-paths/-/env-paths-2.2.1.tgz"
   integrity sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A==
 
 error-ex@^1.3.1:
   version "1.3.2"
-  resolved "https://registry.yarnpkg.com/error-ex/-/error-ex-1.3.2.tgz#b4ac40648107fdcdcfae242f428bea8a14d4f1bf"
+  resolved "https://registry.npmjs.org/error-ex/-/error-ex-1.3.2.tgz"
   integrity sha512-7dFHNmqeFSEt2ZBsCriorKnn3Z2pj+fd9kmI6QoWw4//DL+icEBfc0U7qJCisqrTsKTjw4fNFy2pW9OqStD84g==
   dependencies:
     is-arrayish "^0.2.1"
 
 escape-string-regexp@^1.0.5:
   version "1.0.5"
-  resolved "https://registry.yarnpkg.com/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz#1b61c0562190a8dff6ae3bb2cf0200ca130b86d4"
+  resolved "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz"
   integrity sha1-G2HAViGQqN/2rjuyzwIAyhMLhtQ=
 
 fast-deep-equal@^3.1.1:
   version "3.1.3"
-  resolved "https://registry.yarnpkg.com/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz#3a7d56b559d6cbc3eb512325244e619a65c6c525"
+  resolved "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz"
   integrity sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==
 
 fast-glob@^3.2.9, fast-glob@^3.3.3:
   version "3.3.3"
-  resolved "https://registry.yarnpkg.com/fast-glob/-/fast-glob-3.3.3.tgz#d06d585ce8dba90a16b0505c543c3ccfb3aeb818"
+  resolved "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.3.tgz"
   integrity sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==
   dependencies:
     "@nodelib/fs.stat" "^2.0.2"
@@ -278,61 +263,61 @@ fast-glob@^3.2.9, fast-glob@^3.3.3:
 
 fastest-levenshtein@^1.0.16:
   version "1.0.16"
-  resolved "https://registry.yarnpkg.com/fastest-levenshtein/-/fastest-levenshtein-1.0.16.tgz#210e61b6ff181de91ea9b3d1b84fdedd47e034e5"
+  resolved "https://registry.npmjs.org/fastest-levenshtein/-/fastest-levenshtein-1.0.16.tgz"
   integrity sha512-eRnCtTTtGZFpQCwhJiUOuxPQWRXVKYDn0b2PeHfXL6/Zi53SLAzAHfVhVWK2AryC/WH05kGfxhFIPvTF0SXQzg==
 
 fastq@^1.6.0:
   version "1.8.0"
-  resolved "https://registry.yarnpkg.com/fastq/-/fastq-1.8.0.tgz#550e1f9f59bbc65fe185cb6a9b4d95357107f481"
+  resolved "https://registry.npmjs.org/fastq/-/fastq-1.8.0.tgz"
   integrity sha512-SMIZoZdLh/fgofivvIkmknUXyPnvxRE3DhtZ5Me3Mrsk5gyPL42F0xr51TdRXskBxHfMp+07bcYzfsYEsSQA9Q==
   dependencies:
     reusify "^1.0.4"
 
-file-entry-cache@^10.1.1:
-  version "10.1.1"
-  resolved "https://registry.yarnpkg.com/file-entry-cache/-/file-entry-cache-10.1.1.tgz#ca46f5c4eb22cc37e4ac30214452a59c297d2119"
-  integrity sha512-zcmsHjg2B2zjuBgjdnB+9q0+cWcgWfykIcsDkWDB4GTPtl1eXUA+gTI6sO0u01AqK3cliHryTU55/b2Ow1hfZg==
+file-entry-cache@^10.1.3:
+  version "10.1.3"
+  resolved "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-10.1.3.tgz"
+  integrity sha512-D+w75Ub8T55yor7fPgN06rkCAUbAYw2vpxJmmjv/GDAcvCnv9g7IvHhIZoxzRZThrXPFI2maeY24pPbtyYU7Lg==
   dependencies:
-    flat-cache "^6.1.10"
+    flat-cache "^6.1.12"
 
 fill-range@^7.1.1:
   version "7.1.1"
-  resolved "https://registry.yarnpkg.com/fill-range/-/fill-range-7.1.1.tgz#44265d3cac07e3ea7dc247516380643754a05292"
+  resolved "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz"
   integrity sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==
   dependencies:
     to-regex-range "^5.0.1"
 
-flat-cache@^6.1.10:
-  version "6.1.10"
-  resolved "https://registry.yarnpkg.com/flat-cache/-/flat-cache-6.1.10.tgz#bf388abca92c213ac55086d678b08362867d6213"
-  integrity sha512-B6/v1f0NwjxzmeOhzfXPGWpKBVA207LS7lehaVKQnFrVktcFRfkzjZZ2gwj2i1TkEUMQht7ZMJbABUT5N+V1Nw==
+flat-cache@^6.1.12:
+  version "6.1.12"
+  resolved "https://registry.npmjs.org/flat-cache/-/flat-cache-6.1.12.tgz"
+  integrity sha512-U+HqqpZPPXP5d24bWuRzjGqVqUcw64k4nZAbruniDwdRg0H10tvN7H6ku1tjhA4rg5B9GS3siEvwO2qjJJ6f8Q==
   dependencies:
-    cacheable "^1.10.0"
+    cacheable "^1.10.3"
     flatted "^3.3.3"
-    hookified "^1.9.1"
+    hookified "^1.10.0"
 
 flatted@^3.3.3:
   version "3.3.3"
-  resolved "https://registry.yarnpkg.com/flatted/-/flatted-3.3.3.tgz#67c8fad95454a7c7abebf74bb78ee74a44023358"
+  resolved "https://registry.npmjs.org/flatted/-/flatted-3.3.3.tgz"
   integrity sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg==
 
 glob-parent@^5.1.2:
   version "5.1.2"
-  resolved "https://registry.yarnpkg.com/glob-parent/-/glob-parent-5.1.2.tgz#869832c58034fe68a4093c17dc15e8340d8401c4"
+  resolved "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz"
   integrity sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==
   dependencies:
     is-glob "^4.0.1"
 
 global-modules@^2.0.0:
   version "2.0.0"
-  resolved "https://registry.yarnpkg.com/global-modules/-/global-modules-2.0.0.tgz#997605ad2345f27f51539bea26574421215c7780"
+  resolved "https://registry.npmjs.org/global-modules/-/global-modules-2.0.0.tgz"
   integrity sha512-NGbfmJBp9x8IxyJSd1P+otYK8vonoJactOogrVfFRIAEY1ukil8RSKDz2Yo7wh1oihl51l/r6W4epkeKJHqL8A==
   dependencies:
     global-prefix "^3.0.0"
 
 global-prefix@^3.0.0:
   version "3.0.0"
-  resolved "https://registry.yarnpkg.com/global-prefix/-/global-prefix-3.0.0.tgz#fc85f73064df69f50421f47f883fe5b913ba9b97"
+  resolved "https://registry.npmjs.org/global-prefix/-/global-prefix-3.0.0.tgz"
   integrity sha512-awConJSVCHVGND6x3tmMaKcQvwXLhjdkmomy2W+Goaui8YPgYgXJZewhg3fWC+DlfqqQuWg8AwqjGTD2nAPVWg==
   dependencies:
     ini "^1.3.5"
@@ -341,7 +326,7 @@ global-prefix@^3.0.0:
 
 globby@^11.1.0:
   version "11.1.0"
-  resolved "https://registry.yarnpkg.com/globby/-/globby-11.1.0.tgz#bd4be98bb042f83d796f7e3811991fbe82a0d34b"
+  resolved "https://registry.npmjs.org/globby/-/globby-11.1.0.tgz"
   integrity sha512-jhIXaOzy1sb8IyocaruWSn1TjmnBVs8Ayhcy83rmxNJ8q2uWKCAj3CnJY+KpGSXCueAPc0i05kVvVKtP1t9S3g==
   dependencies:
     array-union "^2.1.0"
@@ -353,52 +338,42 @@ globby@^11.1.0:
 
 globjoin@^0.1.4:
   version "0.1.4"
-  resolved "https://registry.yarnpkg.com/globjoin/-/globjoin-0.1.4.tgz#2f4494ac8919e3767c5cbb691e9f463324285d43"
+  resolved "https://registry.npmjs.org/globjoin/-/globjoin-0.1.4.tgz"
   integrity sha1-L0SUrIkZ43Z8XLtpHp9GMyQoXUM=
 
 has-flag@^3.0.0:
   version "3.0.0"
-  resolved "https://registry.yarnpkg.com/has-flag/-/has-flag-3.0.0.tgz#b5d454dc2199ae225699f3467e5a07f3b955bafd"
+  resolved "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz"
   integrity sha1-tdRU3CGZriJWmfNGfloH87lVuv0=
 
 has-flag@^4.0.0:
   version "4.0.0"
-  resolved "https://registry.yarnpkg.com/has-flag/-/has-flag-4.0.0.tgz#944771fd9c81c81265c4d6941860da06bb59479b"
+  resolved "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz"
   integrity sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==
 
-hookified@^1.8.2:
-  version "1.9.0"
-  resolved "https://registry.yarnpkg.com/hookified/-/hookified-1.9.0.tgz#271211f61c63b3a68a8ead9d9fddd72b5806c004"
-  integrity sha512-2yEEGqphImtKIe1NXWEhu6yD3hlFR4Mxk4Mtp3XEyScpSt4pQ4ymmXA1zzxZpj99QkFK+nN0nzjeb2+RUi/6CQ==
-
-hookified@^1.9.1:
-  version "1.9.1"
-  resolved "https://registry.yarnpkg.com/hookified/-/hookified-1.9.1.tgz#d30cb77590672a05029b7ea9adf25b71c406121d"
-  integrity sha512-u3pxtGhKjcSXnGm1CX6aXS9xew535j3lkOCegbA6jdyh0BaAjTbXI4aslKstCr6zUNtoCxFGFKwjbSHdGrMB8g==
+hookified@^1.10.0:
+  version "1.11.0"
+  resolved "https://registry.npmjs.org/hookified/-/hookified-1.11.0.tgz"
+  integrity sha512-aDdIN3GyU5I6wextPplYdfmWCo+aLmjjVbntmX6HLD5RCi/xKsivYEBhnRD+d9224zFf008ZpLMPlWF0ZodYZw==
 
 html-tags@^3.3.1:
   version "3.3.1"
-  resolved "https://registry.yarnpkg.com/html-tags/-/html-tags-3.3.1.tgz#a04026a18c882e4bba8a01a3d39cfe465d40b5ce"
+  resolved "https://registry.npmjs.org/html-tags/-/html-tags-3.3.1.tgz"
   integrity sha512-ztqyC3kLto0e9WbNp0aeP+M3kTt+nbaIveGmUxAtZa+8iFgKLUOD4YKM5j+f3QD89bra7UeumolZHKuOXnTmeQ==
 
-ieee754@^1.2.1:
-  version "1.2.1"
-  resolved "https://registry.yarnpkg.com/ieee754/-/ieee754-1.2.1.tgz#8eb7a10a63fff25d15a57b001586d177d1b0d352"
-  integrity sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==
-
 ignore@^5.2.0:
   version "5.3.2"
-  resolved "https://registry.yarnpkg.com/ignore/-/ignore-5.3.2.tgz#3cd40e729f3643fd87cb04e50bf0eb722bc596f5"
+  resolved "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz"
   integrity sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==
 
 ignore@^7.0.5:
   version "7.0.5"
-  resolved "https://registry.yarnpkg.com/ignore/-/ignore-7.0.5.tgz#4cb5f6cd7d4c7ab0365738c7aea888baa6d7efd9"
+  resolved "https://registry.npmjs.org/ignore/-/ignore-7.0.5.tgz"
   integrity sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==
 
 import-fresh@^3.3.0:
   version "3.3.0"
-  resolved "https://registry.yarnpkg.com/import-fresh/-/import-fresh-3.3.0.tgz#37162c25fcb9ebaa2e6e53d5b4d88ce17d9e0c2b"
+  resolved "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.0.tgz"
   integrity sha512-veYYhQa+D1QBKznvhUHxb8faxlrwUnxseDAbAp457E0wLNio2bOSKnjYDhMj+YiAq61xrMGhQk9iXVk5FzgQMw==
   dependencies:
     parent-module "^1.0.0"
@@ -406,133 +381,133 @@ import-fresh@^3.3.0:
 
 imurmurhash@^0.1.4:
   version "0.1.4"
-  resolved "https://registry.yarnpkg.com/imurmurhash/-/imurmurhash-0.1.4.tgz#9218b9b2b928a238b13dc4fb6b6d576f231453ea"
+  resolved "https://registry.npmjs.org/imurmurhash/-/imurmurhash-0.1.4.tgz"
   integrity sha1-khi5srkoojixPcT7a21XbyMUU+o=
 
 ini@^1.3.5:
   version "1.3.8"
-  resolved "https://registry.yarnpkg.com/ini/-/ini-1.3.8.tgz#a29da425b48806f34767a4efce397269af28432c"
+  resolved "https://registry.npmjs.org/ini/-/ini-1.3.8.tgz"
   integrity sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==
 
 is-arrayish@^0.2.1:
   version "0.2.1"
-  resolved "https://registry.yarnpkg.com/is-arrayish/-/is-arrayish-0.2.1.tgz#77c99840527aa8ecb1a8ba697b80645a7a926a9d"
+  resolved "https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.2.1.tgz"
   integrity sha1-d8mYQFJ6qOyxqLppe4BkWnqSap0=
 
 is-extglob@^2.1.1:
   version "2.1.1"
-  resolved "https://registry.yarnpkg.com/is-extglob/-/is-extglob-2.1.1.tgz#a88c02535791f02ed37c76a1b9ea9773c833f8c2"
+  resolved "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz"
   integrity sha1-qIwCU1eR8C7TfHahueqXc8gz+MI=
 
 is-fullwidth-code-point@^3.0.0:
   version "3.0.0"
-  resolved "https://registry.yarnpkg.com/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz#f116f8064fe90b3f7844a38997c0b75051269f1d"
+  resolved "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz"
   integrity sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==
 
 is-glob@^4.0.1:
   version "4.0.1"
-  resolved "https://registry.yarnpkg.com/is-glob/-/is-glob-4.0.1.tgz#7567dbe9f2f5e2467bc77ab83c4a29482407a5dc"
+  resolved "https://registry.npmjs.org/is-glob/-/is-glob-4.0.1.tgz"
   integrity sha512-5G0tKtBTFImOqDnLB2hG6Bp2qcKEFduo4tZu9MT/H6NQv/ghhy30o55ufafxJ/LdH79LLs2Kfrn85TLKyA7BUg==
   dependencies:
     is-extglob "^2.1.1"
 
 is-number@^7.0.0:
   version "7.0.0"
-  resolved "https://registry.yarnpkg.com/is-number/-/is-number-7.0.0.tgz#7535345b896734d5f80c4d06c50955527a14f12b"
+  resolved "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz"
   integrity sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==
 
 is-plain-object@^5.0.0:
   version "5.0.0"
-  resolved "https://registry.yarnpkg.com/is-plain-object/-/is-plain-object-5.0.0.tgz#4427f50ab3429e9025ea7d52e9043a9ef4159344"
+  resolved "https://registry.npmjs.org/is-plain-object/-/is-plain-object-5.0.0.tgz"
   integrity sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q==
 
 isexe@^2.0.0:
   version "2.0.0"
-  resolved "https://registry.yarnpkg.com/isexe/-/isexe-2.0.0.tgz#e8fbf374dc556ff8947a10dcb0572d633f2cfa10"
+  resolved "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz"
   integrity sha1-6PvzdNxVb/iUehDcsFctYz8s+hA=
 
 js-tokens@^4.0.0:
   version "4.0.0"
-  resolved "https://registry.yarnpkg.com/js-tokens/-/js-tokens-4.0.0.tgz#19203fb59991df98e3a287050d4647cdeaf32499"
+  resolved "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz"
   integrity sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==
 
 js-yaml@^4.1.0:
   version "4.1.0"
-  resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-4.1.0.tgz#c1fb65f8f5017901cdd2c951864ba18458a10602"
+  resolved "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz"
   integrity sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==
   dependencies:
     argparse "^2.0.1"
 
 json-parse-even-better-errors@^2.3.0:
   version "2.3.1"
-  resolved "https://registry.yarnpkg.com/json-parse-even-better-errors/-/json-parse-even-better-errors-2.3.1.tgz#7c47805a94319928e05777405dc12e1f7a4ee02d"
+  resolved "https://registry.npmjs.org/json-parse-even-better-errors/-/json-parse-even-better-errors-2.3.1.tgz"
   integrity sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==
 
 json-schema-traverse@^1.0.0:
   version "1.0.0"
-  resolved "https://registry.yarnpkg.com/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz#ae7bcb3656ab77a73ba5c49bf654f38e6b6860e2"
+  resolved "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz"
   integrity sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==
 
-keyv@^5.3.3:
-  version "5.3.3"
-  resolved "https://registry.yarnpkg.com/keyv/-/keyv-5.3.3.tgz#ec2d723fbd7b908de5ee7f56b769d46dbbeaf8ba"
-  integrity sha512-Rwu4+nXI9fqcxiEHtbkvoes2X+QfkTRo1TMkPfwzipGsJlJO/z69vqB4FNl9xJ3xCpAcbkvmEabZfPzrwN3+gQ==
+keyv@^5.4.0:
+  version "5.4.0"
+  resolved "https://registry.npmjs.org/keyv/-/keyv-5.4.0.tgz"
+  integrity sha512-TMckyVjEoacG5IteUpUrOBsFORtheqziVyyY2dLUwg1jwTb8u48LX4TgmtogkNl9Y9unaEJ1luj10fGyjMGFOQ==
   dependencies:
-    "@keyv/serialize" "^1.0.3"
+    "@keyv/serialize" "^1.1.0"
 
 kind-of@^6.0.2:
   version "6.0.3"
-  resolved "https://registry.yarnpkg.com/kind-of/-/kind-of-6.0.3.tgz#07c05034a6c349fa06e24fa35aa76db4580ce4dd"
+  resolved "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz"
   integrity sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==
 
 known-css-properties@^0.36.0:
   version "0.36.0"
-  resolved "https://registry.yarnpkg.com/known-css-properties/-/known-css-properties-0.36.0.tgz#5c4365f3c9549ca2e813d2e729e6c47ef6a6cb60"
+  resolved "https://registry.npmjs.org/known-css-properties/-/known-css-properties-0.36.0.tgz"
   integrity sha512-A+9jP+IUmuQsNdsLdcg6Yt7voiMF/D4K83ew0OpJtpu+l34ef7LaohWV0Rc6KNvzw6ZDizkqfyB5JznZnzuKQA==
 
 known-css-properties@^0.37.0:
   version "0.37.0"
-  resolved "https://registry.yarnpkg.com/known-css-properties/-/known-css-properties-0.37.0.tgz#10ebe49b9dbb6638860ff8a002fb65a053f4aec5"
+  resolved "https://registry.npmjs.org/known-css-properties/-/known-css-properties-0.37.0.tgz"
   integrity sha512-JCDrsP4Z1Sb9JwG0aJ8Eo2r7k4Ou5MwmThS/6lcIe1ICyb7UBJKGRIUUdqc2ASdE/42lgz6zFUnzAIhtXnBVrQ==
 
 lines-and-columns@^1.1.6:
   version "1.1.6"
-  resolved "https://registry.yarnpkg.com/lines-and-columns/-/lines-and-columns-1.1.6.tgz#1c00c743b433cd0a4e80758f7b64a57440d9ff00"
+  resolved "https://registry.npmjs.org/lines-and-columns/-/lines-and-columns-1.1.6.tgz"
   integrity sha1-HADHQ7QzzQpOgHWPe2SldEDZ/wA=
 
 lodash.truncate@^4.4.2:
   version "4.4.2"
-  resolved "https://registry.yarnpkg.com/lodash.truncate/-/lodash.truncate-4.4.2.tgz#5a350da0b1113b837ecfffd5812cbe58d6eae193"
+  resolved "https://registry.npmjs.org/lodash.truncate/-/lodash.truncate-4.4.2.tgz"
   integrity sha1-WjUNoLERO4N+z//VgSy+WNbq4ZM=
 
 mathml-tag-names@^2.1.3:
   version "2.1.3"
-  resolved "https://registry.yarnpkg.com/mathml-tag-names/-/mathml-tag-names-2.1.3.tgz#4ddadd67308e780cf16a47685878ee27b736a0a3"
+  resolved "https://registry.npmjs.org/mathml-tag-names/-/mathml-tag-names-2.1.3.tgz"
   integrity sha512-APMBEanjybaPzUrfqU0IMU5I0AswKMH7k8OTLs0vvV4KZpExkTkY87nR/zpbuTPj+gARop7aGUbl11pnDfW6xg==
 
 mdn-data@2.12.2:
   version "2.12.2"
-  resolved "https://registry.yarnpkg.com/mdn-data/-/mdn-data-2.12.2.tgz#9ae6c41a9e65adf61318b32bff7b64fbfb13f8cf"
+  resolved "https://registry.npmjs.org/mdn-data/-/mdn-data-2.12.2.tgz"
   integrity sha512-IEn+pegP1aManZuckezWCO+XZQDplx1366JoVhTpMpBB1sPey/SbveZQUosKiKiGYjg1wH4pMlNgXbCiYgihQA==
 
 mdn-data@^2.21.0:
   version "2.21.0"
-  resolved "https://registry.yarnpkg.com/mdn-data/-/mdn-data-2.21.0.tgz#f3a495e8b1e60cb4fbeaf9136aefba2f987a56e1"
+  resolved "https://registry.npmjs.org/mdn-data/-/mdn-data-2.21.0.tgz"
   integrity sha512-+ZKPQezM5vYJIkCxaC+4DTnRrVZR1CgsKLu5zsQERQx6Tea8Y+wMx5A24rq8A8NepCeatIQufVAekKNgiBMsGQ==
 
 meow@^13.2.0:
   version "13.2.0"
-  resolved "https://registry.yarnpkg.com/meow/-/meow-13.2.0.tgz#6b7d63f913f984063b3cc261b6e8800c4cd3474f"
+  resolved "https://registry.npmjs.org/meow/-/meow-13.2.0.tgz"
   integrity sha512-pxQJQzB6djGPXh08dacEloMFopsOqGVRKFPYvPOt9XDZ1HasbgDZA74CJGreSU4G3Ak7EFJGoiH2auq+yXISgA==
 
 merge2@^1.3.0, merge2@^1.4.1:
   version "1.4.1"
-  resolved "https://registry.yarnpkg.com/merge2/-/merge2-1.4.1.tgz#4368892f885e907455a6fd7dc55c0c9d404990ae"
+  resolved "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz"
   integrity sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==
 
 micromatch@^4.0.8:
   version "4.0.8"
-  resolved "https://registry.yarnpkg.com/micromatch/-/micromatch-4.0.8.tgz#d66fa18f3a47076789320b9b1af32bd86d9fa202"
+  resolved "https://registry.npmjs.org/micromatch/-/micromatch-4.0.8.tgz"
   integrity sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==
   dependencies:
     braces "^3.0.3"
@@ -540,29 +515,29 @@ micromatch@^4.0.8:
 
 ms@^2.1.3:
   version "2.1.3"
-  resolved "https://registry.yarnpkg.com/ms/-/ms-2.1.3.tgz#574c8138ce1d2b5861f0b44579dbadd60c6615b2"
+  resolved "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz"
   integrity sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==
 
 nanoid@^3.3.11:
   version "3.3.11"
-  resolved "https://registry.yarnpkg.com/nanoid/-/nanoid-3.3.11.tgz#4f4f112cefbe303202f2199838128936266d185b"
+  resolved "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz"
   integrity sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==
 
 normalize-path@^3.0.0:
   version "3.0.0"
-  resolved "https://registry.yarnpkg.com/normalize-path/-/normalize-path-3.0.0.tgz#0dcd69ff23a1c9b11fd0978316644a0388216a65"
+  resolved "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz"
   integrity sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==
 
 parent-module@^1.0.0:
   version "1.0.1"
-  resolved "https://registry.yarnpkg.com/parent-module/-/parent-module-1.0.1.tgz#691d2709e78c79fae3a156622452d00762caaaa2"
+  resolved "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz"
   integrity sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==
   dependencies:
     callsites "^3.0.0"
 
 parse-json@^5.2.0:
   version "5.2.0"
-  resolved "https://registry.yarnpkg.com/parse-json/-/parse-json-5.2.0.tgz#c76fc66dee54231c962b22bcc8a72cf2f99753cd"
+  resolved "https://registry.npmjs.org/parse-json/-/parse-json-5.2.0.tgz"
   integrity sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==
   dependencies:
     "@babel/code-frame" "^7.0.0"
@@ -572,114 +547,114 @@ parse-json@^5.2.0:
 
 path-type@^4.0.0:
   version "4.0.0"
-  resolved "https://registry.yarnpkg.com/path-type/-/path-type-4.0.0.tgz#84ed01c0a7ba380afe09d90a8c180dcd9d03043b"
+  resolved "https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz"
   integrity sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==
 
 picocolors@^1.1.1:
   version "1.1.1"
-  resolved "https://registry.yarnpkg.com/picocolors/-/picocolors-1.1.1.tgz#3d321af3eab939b083c8f929a1d12cda81c26b6b"
+  resolved "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz"
   integrity sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==
 
 picomatch@^2.3.1:
   version "2.3.1"
-  resolved "https://registry.yarnpkg.com/picomatch/-/picomatch-2.3.1.tgz#3ba3833733646d9d3e4995946c1365a67fb07a42"
+  resolved "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz"
   integrity sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==
 
 postcss-media-query-parser@^0.2.3:
   version "0.2.3"
-  resolved "https://registry.yarnpkg.com/postcss-media-query-parser/-/postcss-media-query-parser-0.2.3.tgz#27b39c6f4d94f81b1a73b8f76351c609e5cef244"
+  resolved "https://registry.npmjs.org/postcss-media-query-parser/-/postcss-media-query-parser-0.2.3.tgz"
   integrity sha1-J7Ocb02U+Bsac7j3Y1HGCeXO8kQ=
 
 postcss-resolve-nested-selector@^0.1.6:
   version "0.1.6"
-  resolved "https://registry.yarnpkg.com/postcss-resolve-nested-selector/-/postcss-resolve-nested-selector-0.1.6.tgz#3d84dec809f34de020372c41b039956966896686"
+  resolved "https://registry.npmjs.org/postcss-resolve-nested-selector/-/postcss-resolve-nested-selector-0.1.6.tgz"
   integrity sha512-0sglIs9Wmkzbr8lQwEyIzlDOOC9bGmfVKcJTaxv3vMmd3uo4o4DerC3En0bnmgceeql9BfC8hRkp7cg0fjdVqw==
 
 postcss-safe-parser@^7.0.1:
   version "7.0.1"
-  resolved "https://registry.yarnpkg.com/postcss-safe-parser/-/postcss-safe-parser-7.0.1.tgz#36e4f7e608111a0ca940fd9712ce034718c40ec0"
+  resolved "https://registry.npmjs.org/postcss-safe-parser/-/postcss-safe-parser-7.0.1.tgz"
   integrity sha512-0AioNCJZ2DPYz5ABT6bddIqlhgwhpHZ/l65YAYo0BCIn0xiDpsnTHz0gnoTGk0OXZW0JRs+cDwL8u/teRdz+8A==
 
 postcss-scss@^4.0.9:
   version "4.0.9"
-  resolved "https://registry.yarnpkg.com/postcss-scss/-/postcss-scss-4.0.9.tgz#a03c773cd4c9623cb04ce142a52afcec74806685"
+  resolved "https://registry.npmjs.org/postcss-scss/-/postcss-scss-4.0.9.tgz"
   integrity sha512-AjKOeiwAitL/MXxQW2DliT28EKukvvbEWx3LBmJIRN8KfBGZbRTxNYW0kSqi1COiTZ57nZ9NW06S6ux//N1c9A==
 
 postcss-selector-parser@^7.1.0:
   version "7.1.0"
-  resolved "https://registry.yarnpkg.com/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz#4d6af97eba65d73bc4d84bcb343e865d7dd16262"
+  resolved "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz"
   integrity sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==
   dependencies:
     cssesc "^3.0.0"
     util-deprecate "^1.0.2"
 
-postcss-sorting@^8.0.2:
-  version "8.0.2"
-  resolved "https://registry.yarnpkg.com/postcss-sorting/-/postcss-sorting-8.0.2.tgz#6393385ece272baf74bee9820fb1b58098e4eeca"
-  integrity sha512-M9dkSrmU00t/jK7rF6BZSZauA5MAaBW4i5EnJXspMwt4iqTh/L9j6fgMnbElEOfyRyfLfVbIHj/R52zHzAPe1Q==
+postcss-sorting@^9.1.0:
+  version "9.1.0"
+  resolved "https://registry.npmjs.org/postcss-sorting/-/postcss-sorting-9.1.0.tgz"
+  integrity sha512-Mn8KJ45HNNG6JBpBizXcyf6LqY/qyqetGcou/nprDnFwBFBLGj0j/sNKV2lj2KMOVOwdXu14aEzqJv8CIV6e8g==
 
 postcss-value-parser@^4.2.0:
   version "4.2.0"
-  resolved "https://registry.yarnpkg.com/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz#723c09920836ba6d3e5af019f92bc0971c02e514"
+  resolved "https://registry.npmjs.org/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz"
   integrity sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==
 
-postcss@^8.4.32, postcss@^8.5.6:
+postcss@^8.5.3, postcss@^8.5.6:
   version "8.5.6"
-  resolved "https://registry.yarnpkg.com/postcss/-/postcss-8.5.6.tgz#2825006615a619b4f62a9e7426cc120b349a8f3c"
+  resolved "https://registry.npmjs.org/postcss/-/postcss-8.5.6.tgz"
   integrity sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==
   dependencies:
     nanoid "^3.3.11"
     picocolors "^1.1.1"
     source-map-js "^1.2.1"
 
-prettier@3.3.3:
-  version "3.3.3"
-  resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.3.3.tgz#30c54fe0be0d8d12e6ae61dbb10109ea00d53105"
-  integrity sha512-i2tDNA0O5IrMO757lfrdQZCc2jPNDVntV0m/+4whiDfWaTKfMNgR7Qz0NAeGz/nRqF4m5/6CLzbP4/liHt12Ew==
+prettier@3.6.2:
+  version "3.6.2"
+  resolved "https://registry.npmjs.org/prettier/-/prettier-3.6.2.tgz"
+  integrity sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==
 
 punycode@^2.1.0:
   version "2.1.1"
-  resolved "https://registry.yarnpkg.com/punycode/-/punycode-2.1.1.tgz#b58b010ac40c22c5657616c8d2c2c02c7bf479ec"
+  resolved "https://registry.npmjs.org/punycode/-/punycode-2.1.1.tgz"
   integrity sha512-XRsRjdf+j5ml+y/6GKHPZbrF/8p2Yga0JPtdqTIY2Xe5ohJPD9saDJJLPvp9+NSBprVvevdXZybnj2cv8OEd0A==
 
 require-from-string@^2.0.2:
   version "2.0.2"
-  resolved "https://registry.yarnpkg.com/require-from-string/-/require-from-string-2.0.2.tgz#89a7fdd938261267318eafe14f9c32e598c36909"
+  resolved "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz"
   integrity sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==
 
 resolve-from@^4.0.0:
   version "4.0.0"
-  resolved "https://registry.yarnpkg.com/resolve-from/-/resolve-from-4.0.0.tgz#4abcd852ad32dd7baabfe9b40e00a36db5f392e6"
+  resolved "https://registry.npmjs.org/resolve-from/-/resolve-from-4.0.0.tgz"
   integrity sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==
 
 resolve-from@^5.0.0:
   version "5.0.0"
-  resolved "https://registry.yarnpkg.com/resolve-from/-/resolve-from-5.0.0.tgz#c35225843df8f776df21c57557bc087e9dfdfc69"
+  resolved "https://registry.npmjs.org/resolve-from/-/resolve-from-5.0.0.tgz"
   integrity sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==
 
 reusify@^1.0.4:
   version "1.0.4"
-  resolved "https://registry.yarnpkg.com/reusify/-/reusify-1.0.4.tgz#90da382b1e126efc02146e90845a88db12925d76"
+  resolved "https://registry.npmjs.org/reusify/-/reusify-1.0.4.tgz"
   integrity sha512-U9nH88a3fc/ekCF1l0/UP1IosiuIjyTh7hBvXVMHYgVcfGvt897Xguj2UOLDeI5BG2m7/uwyaLVT6fbtCwTyzw==
 
 run-parallel@^1.1.9:
   version "1.1.9"
-  resolved "https://registry.yarnpkg.com/run-parallel/-/run-parallel-1.1.9.tgz#c9dd3a7cf9f4b2c4b6244e173a6ed866e61dd679"
+  resolved "https://registry.npmjs.org/run-parallel/-/run-parallel-1.1.9.tgz"
   integrity sha512-DEqnSRTDw/Tc3FXf49zedI638Z9onwUotBMiUFKmrO2sdFKIbXamXGQ3Axd4qgphxKB4kw/qP1w5kTxnfU1B9Q==
 
 signal-exit@^4.0.1:
   version "4.0.2"
-  resolved "https://registry.yarnpkg.com/signal-exit/-/signal-exit-4.0.2.tgz#ff55bb1d9ff2114c13b400688fa544ac63c36967"
+  resolved "https://registry.npmjs.org/signal-exit/-/signal-exit-4.0.2.tgz"
   integrity sha512-MY2/qGx4enyjprQnFaZsHib3Yadh3IXyV2C321GY0pjGfVBu4un0uDJkwgdxqO+Rdx8JMT8IfJIRwbYVz3Ob3Q==
 
 slash@^3.0.0:
   version "3.0.0"
-  resolved "https://registry.yarnpkg.com/slash/-/slash-3.0.0.tgz#6539be870c165adbd5240220dbe361f1bc4d4634"
+  resolved "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz"
   integrity sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==
 
 slice-ansi@^4.0.0:
   version "4.0.0"
-  resolved "https://registry.yarnpkg.com/slice-ansi/-/slice-ansi-4.0.0.tgz#500e8dd0fd55b05815086255b3195adf2a45fe6b"
+  resolved "https://registry.npmjs.org/slice-ansi/-/slice-ansi-4.0.0.tgz"
   integrity sha512-qMCMfhY040cVHT43K9BFygqYbUPFZKHOg7K73mtTWJRb8pyP3fzf4Ixd5SzdEJQ6MRUg/WBnOLxghZtKKurENQ==
   dependencies:
     ansi-styles "^4.0.0"
@@ -688,17 +663,17 @@ slice-ansi@^4.0.0:
 
 source-map-js@^1.0.1:
   version "1.0.2"
-  resolved "https://registry.yarnpkg.com/source-map-js/-/source-map-js-1.0.2.tgz#adbc361d9c62df380125e7f161f71c826f1e490c"
+  resolved "https://registry.npmjs.org/source-map-js/-/source-map-js-1.0.2.tgz"
   integrity sha512-R0XvVJ9WusLiqTCEiGCmICCMplcCkIwwR11mOSD9CR5u+IXYdiseeEuXCVAjS54zqwkLcPNnmU4OeJ6tUrWhDw==
 
 source-map-js@^1.2.1:
   version "1.2.1"
-  resolved "https://registry.yarnpkg.com/source-map-js/-/source-map-js-1.2.1.tgz#1ce5650fddd87abc099eda37dcff024c2667ae46"
+  resolved "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz"
   integrity sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==
 
 string-width@^4.2.3:
   version "4.2.3"
-  resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010"
+  resolved "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz"
   integrity sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==
   dependencies:
     emoji-regex "^8.0.0"
@@ -707,19 +682,19 @@ string-width@^4.2.3:
 
 strip-ansi@^6.0.1:
   version "6.0.1"
-  resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-6.0.1.tgz#9e26c63d30f53443e9489495b2105d37b67a85d9"
+  resolved "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz"
   integrity sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==
   dependencies:
     ansi-regex "^5.0.1"
 
 stylelint-config-recess-order@7.1.0:
   version "7.1.0"
-  resolved "https://registry.yarnpkg.com/stylelint-config-recess-order/-/stylelint-config-recess-order-7.1.0.tgz#393b52b902362d924ab3bae7ab394232890f94aa"
+  resolved "https://registry.npmjs.org/stylelint-config-recess-order/-/stylelint-config-recess-order-7.1.0.tgz"
   integrity sha512-rFc4Z6SCGgEohr1khsmAZ83X56Tdi2dHY/GB7VT3qJkpKU1V2w+mYlK+b7Za5gpsxEng3jnb4FzWyIl/KTH0AQ==
 
 stylelint-config-recommended-scss@15.0.1:
   version "15.0.1"
-  resolved "https://registry.yarnpkg.com/stylelint-config-recommended-scss/-/stylelint-config-recommended-scss-15.0.1.tgz#87646e7b0645dbe40abb2c63c594e94501a7451f"
+  resolved "https://registry.npmjs.org/stylelint-config-recommended-scss/-/stylelint-config-recommended-scss-15.0.1.tgz"
   integrity sha512-V24bxkNkFGggqPVJlP9iXaBabwSGEG7QTz+PyxrRtjPkcF+/NsWtB3tKYvFYEmczRkWiIEfuFMhGpJFj9Fxe6Q==
   dependencies:
     postcss-scss "^4.0.9"
@@ -728,20 +703,20 @@ stylelint-config-recommended-scss@15.0.1:
 
 stylelint-config-recommended@^16.0.0:
   version "16.0.0"
-  resolved "https://registry.yarnpkg.com/stylelint-config-recommended/-/stylelint-config-recommended-16.0.0.tgz#0221f19902816fe7d53d9a01eb0be4cc7b4fe80a"
+  resolved "https://registry.npmjs.org/stylelint-config-recommended/-/stylelint-config-recommended-16.0.0.tgz"
   integrity sha512-4RSmPjQegF34wNcK1e1O3Uz91HN8P1aFdFzio90wNK9mjgAI19u5vsU868cVZboKzCaa5XbpvtTzAAGQAxpcXA==
 
-stylelint-order@6.0.4:
-  version "6.0.4"
-  resolved "https://registry.yarnpkg.com/stylelint-order/-/stylelint-order-6.0.4.tgz#3e80d876c61a98d2640de181433686f24284748b"
-  integrity sha512-0UuKo4+s1hgQ/uAxlYU4h0o0HS4NiQDud0NAUNI0aa8FJdmYHA5ZZTFHiV5FpmE3071e9pZx5j0QpVJW5zOCUA==
+stylelint-order@7.0.0:
+  version "7.0.0"
+  resolved "https://registry.npmjs.org/stylelint-order/-/stylelint-order-7.0.0.tgz"
+  integrity sha512-rSWxx0KscYfxU02wEskKXES9lkRzuuONMMNkZ7SUc6uiF3tDKm7e+sE0Ax/SBlG4TUf1sp1R6f3/SlsPGmzthg==
   dependencies:
-    postcss "^8.4.32"
-    postcss-sorting "^8.0.2"
+    postcss "^8.5.3"
+    postcss-sorting "^9.1.0"
 
 stylelint-scss@6.12.1, stylelint-scss@^6.12.0:
   version "6.12.1"
-  resolved "https://registry.yarnpkg.com/stylelint-scss/-/stylelint-scss-6.12.1.tgz#7de9980a7c9acb7a3f203498e7296526cb52ffa0"
+  resolved "https://registry.npmjs.org/stylelint-scss/-/stylelint-scss-6.12.1.tgz"
   integrity sha512-UJUfBFIvXfly8WKIgmqfmkGKPilKB4L5j38JfsDd+OCg2GBdU0vGUV08Uw82tsRZzd4TbsUURVVNGeOhJVF7pA==
   dependencies:
     css-tree "^3.0.1"
@@ -753,10 +728,10 @@ stylelint-scss@6.12.1, stylelint-scss@^6.12.0:
     postcss-selector-parser "^7.1.0"
     postcss-value-parser "^4.2.0"
 
-stylelint@16.22.0:
-  version "16.22.0"
-  resolved "https://registry.yarnpkg.com/stylelint/-/stylelint-16.22.0.tgz#00020f4390a8625cf7f707820c1b6b538e4b0fa3"
-  integrity sha512-SVEMTdjKNV4ollUrIY9ordZ36zHv2/PHzPjfPMau370MlL2VYXeLgSNMMiEbLGRO8RmD2R8/BVUeF2DfnfkC0w==
+stylelint@16.23.0:
+  version "16.23.0"
+  resolved "https://registry.npmjs.org/stylelint/-/stylelint-16.23.0.tgz"
+  integrity sha512-69T5aS2LUY306ekt1Q1oaSPwz/jaG9HjyMix3UMrai1iEbuOafBe2Dh8xlyczrxFAy89qcKyZWWtc42XLx3Bbw==
   dependencies:
     "@csstools/css-parser-algorithms" "^3.0.5"
     "@csstools/css-tokenizer" "^3.0.4"
@@ -771,7 +746,7 @@ stylelint@16.22.0:
     debug "^4.4.1"
     fast-glob "^3.3.3"
     fastest-levenshtein "^1.0.16"
-    file-entry-cache "^10.1.1"
+    file-entry-cache "^10.1.3"
     global-modules "^2.0.0"
     globby "^11.1.0"
     globjoin "^0.1.4"
@@ -799,21 +774,21 @@ stylelint@16.22.0:
 
 supports-color@^5.3.0:
   version "5.5.0"
-  resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-5.5.0.tgz#e2e69a44ac8772f78a1ec0b35b689df6530efc8f"
+  resolved "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz"
   integrity sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==
   dependencies:
     has-flag "^3.0.0"
 
 supports-color@^7.0.0:
   version "7.2.0"
-  resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-7.2.0.tgz#1b7dcdcb32b8138801b3e478ba6a51caa89648da"
+  resolved "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz"
   integrity sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==
   dependencies:
     has-flag "^4.0.0"
 
 supports-hyperlinks@^3.2.0:
   version "3.2.0"
-  resolved "https://registry.yarnpkg.com/supports-hyperlinks/-/supports-hyperlinks-3.2.0.tgz#b8e485b179681dea496a1e7abdf8985bd3145461"
+  resolved "https://registry.npmjs.org/supports-hyperlinks/-/supports-hyperlinks-3.2.0.tgz"
   integrity sha512-zFObLMyZeEwzAoKCyu1B91U79K2t7ApXuQfo8OuxwXLDgcKxuwM+YvcbIhm6QWqz7mHUH1TVytR1PwVVjEuMig==
   dependencies:
     has-flag "^4.0.0"
@@ -821,12 +796,12 @@ supports-hyperlinks@^3.2.0:
 
 svg-tags@^1.0.0:
   version "1.0.0"
-  resolved "https://registry.yarnpkg.com/svg-tags/-/svg-tags-1.0.0.tgz#58f71cee3bd519b59d4b2a843b6c7de64ac04764"
+  resolved "https://registry.npmjs.org/svg-tags/-/svg-tags-1.0.0.tgz"
   integrity sha1-WPcc7jvVGbWdSyqEO2x95krAR2Q=
 
 table@^6.9.0:
   version "6.9.0"
-  resolved "https://registry.yarnpkg.com/table/-/table-6.9.0.tgz#50040afa6264141c7566b3b81d4d82c47a8668f5"
+  resolved "https://registry.npmjs.org/table/-/table-6.9.0.tgz"
   integrity sha512-9kY+CygyYM6j02t5YFHbNz2FN5QmYGv9zAjVp4lCDjlCw7amdckXlEt/bjMhUIfj4ThGRE4gCUH5+yGnNuPo5A==
   dependencies:
     ajv "^8.0.1"
@@ -837,33 +812,33 @@ table@^6.9.0:
 
 to-regex-range@^5.0.1:
   version "5.0.1"
-  resolved "https://registry.yarnpkg.com/to-regex-range/-/to-regex-range-5.0.1.tgz#1648c44aae7c8d988a326018ed72f5b4dd0392e4"
+  resolved "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz"
   integrity sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==
   dependencies:
     is-number "^7.0.0"
 
 uri-js@^4.2.2:
   version "4.2.2"
-  resolved "https://registry.yarnpkg.com/uri-js/-/uri-js-4.2.2.tgz#94c540e1ff772956e2299507c010aea6c8838eb0"
+  resolved "https://registry.npmjs.org/uri-js/-/uri-js-4.2.2.tgz"
   integrity sha512-KY9Frmirql91X2Qgjry0Wd4Y+YTdrdZheS8TFwvkbLWf/G5KNJDCh6pKL5OZctEW4+0Baa5idK2ZQuELRwPznQ==
   dependencies:
     punycode "^2.1.0"
 
 util-deprecate@^1.0.2:
   version "1.0.2"
-  resolved "https://registry.yarnpkg.com/util-deprecate/-/util-deprecate-1.0.2.tgz#450d4dc9fa70de732762fbd2d4a28981419a0ccf"
+  resolved "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz"
   integrity sha1-RQ1Nyfpw3nMnYvvS1KKJgUGaDM8=
 
 which@^1.3.1:
   version "1.3.1"
-  resolved "https://registry.yarnpkg.com/which/-/which-1.3.1.tgz#a45043d54f5805316da8d62f9f50918d3da70b0a"
+  resolved "https://registry.npmjs.org/which/-/which-1.3.1.tgz"
   integrity sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ==
   dependencies:
     isexe "^2.0.0"
 
 write-file-atomic@^5.0.1:
   version "5.0.1"
-  resolved "https://registry.yarnpkg.com/write-file-atomic/-/write-file-atomic-5.0.1.tgz#68df4717c55c6fa4281a7860b4c2ba0a6d2b11e7"
+  resolved "https://registry.npmjs.org/write-file-atomic/-/write-file-atomic-5.0.1.tgz"
   integrity sha512-+QU2zd6OTD8XWIJCbffaiQeH9U73qIqafo1x6V1snCWYGJf6cVE0cDR4D8xRzcEnfI21IFrUPzPGtcPf8AC+Rw==
   dependencies:
     imurmurhash "^0.1.4"