feat: reorder ruby-gem contents & dedupe

gildesmarais · gildesmarais · commit 1c7701146c5f · 2025-08-02T13:21:43.000+02:00
diff --git 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
@@ -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
@@ -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
@@ -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
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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/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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
diff --git a/ruby-gem/tutorials/index.md 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/tutorials/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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
diff --git a/web-application/installation.md b/web-application/installation.md
diff --git a/web-application/reference/index.md b/web-application/reference/index.md
diff --git a/web-application/tutorials/index.md b/web-application/tutorials/index.md
