docs(onboarding): make docker the default path

Author: gildesmarais

src/content/docs/creating-custom-feeds.mdx

@@ -19,6 +19,12 @@ When auto-sourcing isn't enough, you can write your own configuration files to c
   releases](/web-application/reference/versioning-and-releases/) for details.
 </Aside>
 
+<Aside type="tip" title="Use this guide when you need more control">
+  Start with included feeds first. If your site is not covered, try [automatic feed
+  generation](/web-application/how-to/use-automatic-feed-generation/) next. Reach for a custom config when you
+  need a stable, reviewable setup or the generated feed misses important content.
+</Aside>
+
 ---
 
 ## When to Use Custom Configs
@@ -35,6 +41,20 @@ When auto-sourcing isn't enough, you can write your own configuration files to c
 
 ---
 
+## Recommended Workflow
+
+1. **Inspect the live page** in your browser developer tools
+2. **Write the smallest useful config** that extracts items, titles, and links
+3. **Validate the config** with `html2rss validate your-config.yml`
+4. **Render the feed** with `html2rss feed your-config.yml`
+5. **Add it to `html2rss-web`** so you can use it through your normal instance
+6. **Escalate to `browserless`** if the content is rendered by JavaScript
+
+This order keeps iteration fast and makes it easier to see whether the problem is the page structure, your
+selectors, or the fetch strategy.
+
+---
+
 ## How It Works
 
 A config file is a simple "recipe" that tells html2rss:
@@ -82,7 +102,7 @@ This says: "Find each article, get the title from the h2 anchor, and get the lin
 
 ## Your First Config
 
-**Step 1:** Look at the website you want to create a feed for. Right-click → "View Page Source" to see the HTML structure.
+**Step 1:** Inspect the website you want to create a feed for. Start with your browser's developer tools to inspect the live DOM. "View Page Source" can still help, but it may miss JavaScript-rendered content.
 
 **Step 2:** Create a file called `example.com.yml` with this basic structure:
 
@@ -140,6 +160,12 @@ html2rss supports many configuration options:
 
 4. **Check the output:** Make sure all items have titles, links, and descriptions
 
+## Add It To html2rss-web
+
+Once the config works locally, add it to your `feeds.yml` or shared config repository and restart your
+instance. Then open the feed through your normal `html2rss-web` URL and confirm it behaves the same way
+there.
+
 ---
 
 ## Sharing Your Config
@@ -177,11 +203,13 @@ html2rss supports many configuration options:
 **For Beginners:**
 
 - **[Browse the Feed Directory](/feed-directory/)** - See real-world examples
+- **[Run html2rss-web with Docker](/web-application/getting-started)** - Use the newest integrated behavior
 - **[Learn more about selectors](/ruby-gem/reference/selectors/)** - Master CSS selectors
 - **[Submit your config via GitHub Web](https://github.com/html2rss/html2rss-configs)** - No Git knowledge required!
 
 **For Contributors:**
 
 - **[Browse existing configs](https://github.com/html2rss/html2rss-configs/tree/master/lib/html2rss/configs)** - See real examples
 - **[Join discussions](https://github.com/orgs/html2rss/discussions)** - Connect with other users
+- **[Learn about strategies](/ruby-gem/reference/strategy/)** - Decide when to use `browserless`
 - **[Learn advanced features](/ruby-gem/how-to/advanced-features/)** - Take your configs to the next level

src/content/docs/getting-started.mdx

@@ -5,37 +5,21 @@ sidebar:
   order: 1
 ---
 
-Ready to get RSS feeds from any website? Choose your path below. No technical knowledge required!
+import { Aside } from "@astrojs/starlight/components";
 
-## Quick Start Options
+Ready to get RSS feeds from any website? Run `html2rss-web` locally with Docker, verify the interface, then start with included feeds before you move on to custom configs.
 
-### Option 1: Use a Public Instance (Easiest)
+## What Success Looks Like
 
-**Try html2rss right now:**
+After this guide, you should have:
 
-1. **Go to a public html2rss instance** (see our [community wiki](https://github.com/html2rss/html2rss-web/wiki/Instances) for available instances)
-2. **Browse existing feeds** or create auto-sourced feeds from any URL
-3. **Copy the RSS URL** and add it to your feed reader
-4. **Done!** You're now following the website in your RSS reader
+- `html2rss-web` running at `http://localhost:3000`
+- a list of working included feeds
+- a clear next step for either auto-generation or custom configs
 
-**Perfect for:** Testing, quick feeds, or if you don't want to install anything.
+## Recommended Path
 
-### Option 2: Install Your Own Instance
-
-**For full control and custom feeds:**
-
-1. **Follow the installation steps below**
-2. **Create auto-sourced feeds** from any website
-3. **Add custom configs** when you need more control
-4. **Run your own RSS feed server** with stable HTTPS URLs
-
-**Perfect for:** Power users, custom configurations, or when you need reliability.
-
----
-
-## Installation Guide
-
-This guide will help you set up your own copy of html2rss-web on your computer. Don't worry - we'll walk you through every step!
+This guide will help you set up your own copy of `html2rss-web` on your computer. Start here if you want the most reliable path and the newest integrated behavior.
 
 ### What You'll Need
 
@@ -55,14 +39,9 @@ mkdir html2rss-web
 cd html2rss-web
 ```
 
-### Step 2: Create the Configuration File
-
-Create a file called `docker-compose.yml` in your new folder. This file tells Docker how to set up html2rss-web with all the features you need.
-
-**How to create the file:**
+### Step 2: Create a Minimal Configuration File
 
-- **Using a text editor:** Create a new file and save it as `docker-compose.yml`
-- **Using terminal:** Use any text editor to create the file
+Create a file called `docker-compose.yml` in your new folder. Start with the minimal local stack:
 
 ```yaml
 services:
@@ -83,14 +62,6 @@ services:
       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
@@ -102,6 +73,8 @@ services:
       TOKEN: 6R0W53R135510
 ```
 
+Add update automation such as Watchtower later, after the first run works.
+
 ### Step 3: Download the Feed List
 
 html2rss-web needs a list of feeds to work with. Download our pre-made list:
@@ -117,48 +90,48 @@ curl https://raw.githubusercontent.com/html2rss/html2rss-web/master/config/feeds
 
 ### Step 4: Start html2rss-web
 
-Now start html2rss-web:
-
-**Start html2rss-web:**
-
 Open a terminal in your html2rss-web folder and run:
 
 ```bash
 docker compose up -d
 ```
 
-**That's it!** 🎉 html2rss-web is now running.
+## First Success Check
 
-**To verify it's working:**
+At this point, `html2rss-web` should be running.
 
 1. Open your web browser
 2. Go to `http://localhost:3000`
 3. You should see the html2rss-web interface with a list of available feeds
 
-**If you see the interface, congratulations!** You've successfully set up html2rss-web.
+If you see the interface, the install worked.
 
 ---
 
-## Using Your Instance
+## What To Do First
 
 ### Browse Existing Feeds
 
-Your html2rss-web instance comes with pre-configured feeds for popular websites. Browse the list and copy any RSS URL to your feed reader.
+Your instance comes with pre-configured feeds for many websites. Browse the list, open one feed, and copy its RSS URL into your feed reader.
 
-### Create Auto-Sourced Feeds
+This is the easiest way to confirm the whole stack is healthy.
 
-**Want a feed for a website that's not in the list?**
+### Then Choose Your Next Step
 
-1. **Go to your html2rss-web interface** (http://localhost:3000)
-2. **Enter any website URL** you want to create a feed for
-3. **Click "Generate Feed"** - html2rss will automatically analyze the page
-4. **Copy the RSS URL** and add it to your feed reader
+- **Included feed works:** keep using the built-in configs and browse the [Feed Directory](/feed-directory/)
+- **Need a feed for a new site:** decide between auto-generation and a custom config
+- **Need stable, repeatable control:** move to [Creating Custom Feeds](/creating-custom-feeds)
 
-**This works for most websites** without any configuration needed!
+<Aside type="note" title="Auto-generation is optional">
+  Automatic feed generation is not enabled by default. If you want the "paste a URL and generate a feed"
+  workflow, follow [Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/).
+</Aside>
 
-### Add Custom Feeds
+## When To Use Each Option
 
-**Need more control?** You can add custom feed configurations to your `feeds.yml` file. See our [Creating Custom Feeds](/creating-custom-feeds) guide for details.
+- **Use included configs** when the site already exists in the directory
+- **Enable automatic feed generation** when you want to try a site quickly without writing YAML
+- **Write a custom config** when auto-generation is incomplete or you need precise control
 
 ---
 
@@ -175,11 +148,7 @@ Your html2rss-web instance comes with pre-configured feeds for popular websites.
 
 ## Next Steps
 
-**Ready for more?**
-
-- **[Browse the Feed Directory](/feed-directory/)** - See real-world examples
-- **[Create Custom Feeds](/creating-custom-feeds)** - Learn to write your own configurations
-- **[Troubleshooting Guide](/troubleshooting/troubleshooting)** - Solve common issues
-- **[Join the Community](https://github.com/orgs/html2rss/discussions)** - Get help and share ideas
-
-**🎉 Congratulations!** You now have your own RSS feed server running.
+1. **[Use the included configs](/web-application/how-to/use-included-configs/)** - Start with working feeds
+2. **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)** - Enable the quick-generate flow
+3. **[Create Custom Feeds](/creating-custom-feeds)** - Add and test your own YAML configs
+4. **[Troubleshooting Guide](/troubleshooting/troubleshooting)** - Solve startup and extraction issues

src/content/docs/index.mdx

@@ -3,11 +3,21 @@ title: "Turn Any Website Into an RSS Feed - Never Miss Updates Again"
 description: "Create RSS feeds from any website - no coding required. Turn blogs, news sites, and forums into RSS feeds you can follow in your favorite reader. Free, open source, and easy to use."
 ---
 
-Ever wished you could follow your favorite websites like a social media feed? The html2rss project makes it possible by creating RSS feeds for any website - even ones that don't offer them.
+Run `html2rss-web` with Docker, start with included feeds, and add custom configs only when you need more control.
 
 ## 🚀 Get Started in 30 Seconds
 
-**Try it now:** [Browse Ready-Made Feeds](/feed-directory/) | [Get Started](/getting-started)
+**Start here:** [Run html2rss-web with Docker](/web-application/getting-started) | [Browse working feed examples](/feed-directory/)
+
+Need more control? [Write a custom feed config](/creating-custom-feeds)
+
+---
+
+## How It Works
+
+1. **Run your own local instance** with Docker
+2. **Use included feeds or add your own** website targets
+3. **Subscribe from your RSS reader** using stable feed URLs
 
 ---
 
@@ -34,30 +44,30 @@ Ever wished you could follow your favorite websites like a social media feed? Th
 
 ## What is html2rss?
 
-html2rss is a user-friendly tool that turns any website into an RSS feed. Think of it as a translator that converts website content into a format your feed reader can understand.
+html2rss is a toolkit for turning websites into RSS feeds. Think of it as a translator that converts website content into a format your feed reader can understand.
 
-**Two ways to use html2rss:**
+**Most people should start with the web application:**
 
-- **🌐 Web App** - RSS feed server with auto-sourcing. Perfect for everyone
-- **⚙️ Ruby Gem** - The core engine that powers everything
+- **🌐 html2rss-web** - The easiest way to run your own feed server with Docker
+- **⚙️ html2rss gem** - The underlying engine, CLI, and developer interface
 
 ---
 
 ## 🎯 Choose Your Path
 
-### I'm Getting Started with RSS
+### I want a working instance first
 
-1. **[Get Started](/getting-started)** - Complete guide to using html2rss
-2. **[Browse Examples](/feed-directory/)** - See 100+ ready-made feeds
-3. **[Learn More](/about/)** - Understand how it all works
+1. **[Run html2rss-web with Docker](/web-application/getting-started)** - Recommended starting path
+2. **[Browse working feed examples](/feed-directory/)** - See what success looks like
+3. **[Use the included configs](/web-application/how-to/use-included-configs/)** - Start with ready-made feeds
 
-### I Want to Create Custom Feeds
+### I need more control
 
-1. **[Creating Custom Feeds](/creating-custom-feeds)** - Learn to write your own configs
-2. **[Ruby Gem Reference](/ruby-gem/)** - Full technical documentation
-3. **[Share Your Configs](/get-involved/contributing/)** - Help the community
+1. **[Creating Custom Feeds](/creating-custom-feeds)** - Write and test your own configs
+2. **[Selectors Reference](/ruby-gem/reference/selectors/)** - Learn the matching rules
+3. **[Strategy Reference](/ruby-gem/reference/strategy/)** - Use `browserless` for JS-heavy sites
 
-### I'm a Developer
+### I'm building or integrating
 
 1. **[Ruby Gem Reference](/ruby-gem/)** - Full API documentation
 2. **[Advanced Features](/ruby-gem/how-to/advanced-features/)** - Custom HTTP requests, etc.
@@ -80,6 +90,12 @@ html2rss is a user-friendly tool that turns any website into an RSS feed. Think
 
 ## 🔧 Common Issues?
 
+**Start with Docker, not a public instance.** That gives you the most reliable path and the newest integrated behavior.
+
 **Feed not working?** Check our [troubleshooting guide](/troubleshooting/troubleshooting)
+
+**Need custom control?** Continue to [Creating Custom Feeds](/creating-custom-feeds)
+
 **Need help?** Join our [community discussions](https://github.com/orgs/html2rss/discussions)
+
 **Found a bug?** [Report it on GitHub](https://github.com/html2rss/html2rss/issues)