html2rss · gildesmarais · Mar 12, 2026 · Mar 12, 2026 · Mar 12, 2026 · Mar 12, 2026
diff --git a/astro.config.mjs b/astro.config.mjs
@@ -248,17 +248,17 @@ export default defineConfig({
       },
       sidebar: [
         {
-          label: "Home",
-          link: "/",
-        },
-        {
-          label: "Common Use Cases",
-          link: "/common-use-cases",
+          label: "Getting Started",
+          link: "/getting-started",
         },
         {
           label: "Feed Directory",
           link: "/feed-directory/",
         },
+        {
+          label: "Create Custom Feeds",
+          link: "/creating-custom-feeds",
+        },
         {
           label: "Web Application",
           collapsed: true,
@@ -299,10 +299,6 @@ export default defineConfig({
             },
           ],
         },
-        {
-          label: "Write Your Own Feed Configs",
-          link: "/creating-custom-feeds",
-        },
         {
           label: "About",
           link: "/about",
@@ -312,11 +308,6 @@ export default defineConfig({
           collapsed: false,
           autogenerate: { directory: "get-involved" },
         },
-        {
-          label: "Troubleshooting",
-          collapsed: true,
-          autogenerate: { directory: "troubleshooting" },
-        },
       ],
       defaultLocale: "root",
       locales: {

diff --git a/src/components/docs/AutoGenerationOptional.astro b/src/components/docs/AutoGenerationOptional.astro
@@ -0,0 +1,8 @@
+---
+import { Aside } from "@astrojs/starlight/components";
+---
+
+<Aside type="note" title="Automatic generation is optional">
+  The "paste a website URL and generate a feed" workflow is not enabled by default. If you want it, continue
+  with <a href="/web-application/how-to/use-automatic-feed-generation/">Use automatic feed generation</a>.
+</Aside>
diff --git a/src/components/docs/MinimalDockerCompose.astro b/src/components/docs/MinimalDockerCompose.astro
@@ -0,0 +1,33 @@
+---
+import Code from "astro/components/Code.astro";
-import Code from "astro/components/Code.astro";
+import { Code } from "@astrojs/starlight/components";
-import Code from "astro/components/Code.astro";
+import { Code } from "@astrojs/starlight/components";
+
+const code = `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: CHANGE_THIS_PASSWORD_BEFORE_USE
+      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:3001
+      BROWSERLESS_IO_API_TOKEN: 6R0W53R135510
+
+  browserless:
+    image: "ghcr.io/browserless/chromium"
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:3001:3001"
+    environment:
+      PORT: 3001
+      CONCURRENT: 10
+      TOKEN: 6R0W53R135510`;
+---
+
+<Code code={code} lang="yaml" />
diff --git a/src/content/docs/creating-custom-feeds.mdx b/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
diff --git a/src/content/docs/getting-started.mdx b/src/content/docs/getting-started.mdx
@@ -5,181 +5,21 @@ sidebar:
   order: 1
 ---
 
-Ready to get RSS feeds from any website? Choose your path below. No technical knowledge required!
+This page points to the main onboarding flow.
 
-## Quick Start Options
+## Start Here
 
-### Option 1: Use a Public Instance (Easiest)
+If you want the recommended path, go to [Run html2rss-web with Docker](/web-application/getting-started).
 
-**Try html2rss right now:**
+That guide is the canonical setup flow for:
 
-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
+- running `html2rss-web` locally
+- confirming your first successful feed
+- deciding when to use included feeds, automatic generation, or custom configs
 
-**Perfect for:** Testing, quick feeds, or if you don't want to install anything.
+## Quick Shortcuts
 
-### 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!
-
-### What You'll Need
-
-- **Docker** - A tool that makes installation simple (like an app store for server software)
-- **About 10 minutes** - The whole process is quick and automated
-
-**Don't have Docker?** [Install it first](https://docs.docker.com/get-started/) - it's free and works on all major operating systems.
-
-### Step 1: Create a Folder
-
-Create a new folder on your computer to store html2rss-web files:
-
-**Create a new folder** on your computer and name it "html2rss-web". You can do this through your file manager or terminal:
-
-```bash
-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:**
-
-- **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
-
-```yaml
-services:
-  html2rss-web:
-    image: gilcreator/html2rss-web:latest
-    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: CHANGE_THIS_PASSWORD_BEFORE_USE
-      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: Download the Feed List
-
-html2rss-web needs a list of feeds to work with. Download our pre-made list:
-
-**Download the feeds.yml file:**
-
-- **Using your browser:** Right-click [this link](https://raw.githubusercontent.com/html2rss/html2rss-web/master/config/feeds.yml) → Save As → Name it "feeds.yml" → Save in your html2rss-web folder
-- **Using terminal:** Open Terminal in your html2rss-web folder and run:
-
-```bash
-curl https://raw.githubusercontent.com/html2rss/html2rss-web/master/config/feeds.yml -o feeds.yml
-```
-
-### 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.
-
-**To verify it's working:**
-
-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.
-
----
-
-## Using Your Instance
-
-### 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.
-
-### Create Auto-Sourced Feeds
-
-**Want a feed for a website that's not in the list?**
-
-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
-
-**This works for most websites** without any configuration needed!
-
-### Add Custom Feeds
-
-**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.
-
----
-
-## Troubleshooting
-
-**Common issues when getting started:**
-
-- **Instance won't start?** Check that Docker is running and the port isn't already in use
-- **Can't access the interface?** Make sure you're going to `http://localhost:3000`
-- **Auto-sourced feed not working?** Some websites need custom configuration - see our [troubleshooting guide](/troubleshooting/troubleshooting)
-- **Need help?** Join our [community discussions](https://github.com/orgs/html2rss/discussions)
-
----
-
-## 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.
+- **[Run html2rss-web with Docker](/web-application/getting-started)** - Recommended first step
+- **[Browse working feed examples](/feed-directory/)** - See what success looks like
+- **[Create Custom Feeds](/creating-custom-feeds)** - Write configs when you need more control
+- **[Troubleshooting Guide](/troubleshooting/troubleshooting)** - Fix startup or extraction problems