Align docs with web app UX flow

gildesmarais · gildesmarais · commit 55d803f5df48 · 2026-03-15T12:44:44.000+01:00
diff --git a/src/components/docs/AutoGenerationOptional.astro b/src/components/docs/AutoGenerationOptional.astro
@@ -2,7 +2,7 @@
 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 type="note" title="Automatic generation may be disabled">
+  The direct `Create a feed` workflow is not enabled on every deployment. If you want that path, continue with
+  <a href="/web-application/how-to/use-automatic-feed-generation/">Use automatic feed generation</a>.
 </Aside>
diff --git a/src/content/docs/creating-custom-feeds.mdx b/src/content/docs/creating-custom-feeds.mdx
@@ -20,9 +20,9 @@ When auto-sourcing isn't enough, you can write your own configuration files to c
 </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.
+  Start with the web interface first. If the direct generation flow is not enough, continue with [automatic
+  feed generation](/web-application/how-to/use-automatic-feed-generation/) or reach for a custom config when
+  you need a stable, reviewable setup.
 </Aside>
 
 ---
diff --git a/src/content/docs/getting-started.mdx b/src/content/docs/getting-started.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Getting Started"
-description: "Learn how to get RSS feeds from any website. Start with existing feeds or create your own in minutes."
+description: "Start html2rss-web locally, verify the web interface, generate your first feed URL, and decide when to move to custom configs."
 sidebar:
   order: 1
 ---
@@ -14,12 +14,14 @@ If you want the recommended path, go to [Run html2rss-web with Docker](/web-appl
 That guide is the canonical setup flow for:
 
 - running `html2rss-web` locally
-- confirming your first successful feed
-- deciding when to use included feeds, automatic generation, or custom configs
+- confirming the interface is working
+- generating a first feed URL
+- deciding when to use automatic generation or custom configs
 
 ## Quick Shortcuts
 
-- **[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
+- **[Run html2rss-web with Docker](/web-application/getting-started)**: recommended first step
+- **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)**: create a feed directly from a page URL
+- **[Browse working feed examples](/feed-directory/)**: see what successful outputs look like
+- **[Create Custom Feeds](/creating-custom-feeds)**: write configs when you need more control
+- **[Troubleshooting Guide](/troubleshooting/troubleshooting)**: fix startup or extraction problems
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
@@ -1,101 +1,69 @@
 ---
-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."
+title: "Turn Any Website Into an RSS Feed"
+description: "Run html2rss-web with Docker, open the web interface, generate stable feed URLs, and move to custom configs only when you need more control."
 ---
 
-Run `html2rss-web` with Docker, start with included feeds, and add custom configs only when you need more control.
+Run `html2rss-web` with Docker, open the web interface, and generate stable feed URLs from pages you want to follow.
 
-## 🚀 Get Started in 30 Seconds
+## Start Here
 
-**Start here:** [Run html2rss-web with Docker](/web-application/getting-started) | [Browse working feed examples](/feed-directory/)
+**Recommended path:** [Run html2rss-web with Docker](/web-application/getting-started)
 
-Need more control? [Write a custom feed config](/creating-custom-feeds)
+That guide is the canonical onboarding flow for:
 
----
+- starting a local instance
+- verifying the web interface
+- generating a first feed URL
+- deciding when to use automatic generation or custom configs
 
 ## 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
-
----
-
-## Why RSS Still Matters Today
-
-**Real examples of what you can do:**
-
-- Follow your favorite blogs without social media algorithms
-- Get notified when your local news site posts about your neighborhood
-- Track job postings from multiple company websites
-- Monitor product updates from software vendors
-- Follow academic papers from your field
-
-**RSS vs Social Media:**
-
-- ✅ **No algorithms** deciding what you see
-- ✅ **No ads** or sponsored content
-- ✅ **Works with any feed reader** you choose
-- ✅ **Your data stays private**
-- ✅ **Never miss updates** - automatic notifications
-- ✅ **Save time** - no more manual checking
-
----
+2. **Open the web interface** and paste a page URL
+3. **Copy the feed URL into your reader**
 
 ## What is html2rss?
 
-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.
+html2rss is a toolkit for turning websites into feeds.
 
-**Most people should start with the web application:**
+Most people should start with the web application:
 
-- **🌐 html2rss-web** - The easiest way to run your own feed server with Docker
-- **⚙️ html2rss gem** - The underlying engine, CLI, and developer interface
+- **`html2rss-web`**: the self-hosted web interface and feed server
+- **`html2rss` gem**: the Ruby engine, CLI, and lower-level config workflow
 
----
-
-## 🎯 Choose Your Path
+## Choose Your Path
 
 ### I want a working instance first
 
-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
+1. **[Run html2rss-web with Docker](/web-application/getting-started)**: recommended starting path
+2. **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)**: create a feed directly from a page URL
+3. **[Browse working feed examples](/feed-directory/)**: see what working outputs look like
 
 ### I need more control
 
-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
+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/)**: decide when `browserless` is justified
 
 ### 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.
-3. **[Contribute to Core](/get-involved/contributing/)** - Help improve the engine
-
----
-
-## 🌟 What People Are Using html2rss For
-
-- **News & Blogs:** Follow your favorite writers without social media
-- **Job Hunting:** Track job postings from multiple company sites
-- **Product Updates:** Get notified when software you use gets updated
-- **Academic Research:** Follow new papers in your field
-- **Local News:** Stay updated on your neighborhood and city
-- **Hobby Communities:** Follow forums and communities you care about
-
-[Browse all examples in our Feed Directory →](/feed-directory/)
-
----
-
-## 🔧 Common Issues?
+1. **[Ruby Gem Reference](/ruby-gem/)**: full API documentation
+2. **[Advanced Features](/ruby-gem/how-to/advanced-features/)**: custom HTTP requests and advanced extraction
+3. **[Contribute to Core](/get-involved/contributing/)**: help improve the engine
 
-**Start with Docker, not a public instance.** That gives you the most reliable path and the newest integrated behavior.
+## What People Use It For
 
-**Feed not working?** Check our [troubleshooting guide](/troubleshooting/troubleshooting)
+- follow blogs and news sites without social media algorithms
+- track product updates and release notes
+- monitor job postings from company websites
+- subscribe to forums and communities that do not publish feeds
+- follow local news without repeated manual checking
 
-**Need custom control?** Continue to [Creating Custom Feeds](/creating-custom-feeds)
+## Practical Notes
 
-**Need help?** Join our [community discussions](https://github.com/orgs/html2rss/discussions)
+- Start with Docker, not a public instance.
+- Use the web interface to verify the deployment first.
+- Use automatic generation for the first pass.
+- Move to custom configs when you need a stable, reviewable setup.
 
-**Found a bug?** [Report it on GitHub](https://github.com/html2rss/html2rss/issues)
+**Need help?** Continue to the [troubleshooting guide](/troubleshooting/troubleshooting) or join [GitHub Discussions](https://github.com/orgs/html2rss/discussions).
diff --git a/src/content/docs/web-application/getting-started.mdx b/src/content/docs/web-application/getting-started.mdx
@@ -1,39 +1,38 @@
 ---
 title: "Getting Started"
-description: "Learn how to use html2rss-web to create RSS feeds from any website. Step-by-step guide for beginners with no technical knowledge required."
+description: "Run html2rss-web locally with Docker, verify the interface, and generate your first feed URL."
 sidebar:
   order: 2
 ---
 
 import AutoGenerationOptional from "../../../components/docs/AutoGenerationOptional.astro";
 import MinimalDockerCompose from "../../../components/docs/MinimalDockerCompose.astro";
 
-Ready to create RSS feeds? Run `html2rss-web` locally with Docker, verify the interface, then use included feeds before you move on to auto-generation or custom configs.
+Run `html2rss-web` locally with Docker, open the web interface, and verify that you can generate a working feed URL.
 
 ## What You Will Have When This Works
 
 After this guide, you should have:
 
 - `html2rss-web` running at `http://localhost:3000`
-- a feed list loaded from `feeds.yml`
-- a clear path to either automatic generation or custom YAML configs
+- the web interface loading correctly
+- a first feed URL you can copy into your reader
+- a clear path to either custom configs or more advanced setup
 
 ## Installation Guide
 
 This guide walks you through a local Docker setup that gives you the most reliable starting point.
 
 ### 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
+- **Docker**
+- **About 10 minutes**
 
-**Don't have Docker?** [Install it first](https://docs.docker.com/get-started/) - it's free and works on all major operating systems.
+If you do not already have Docker, [install it first](https://docs.docker.com/get-started/).
 
 ### 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:
+Create a new folder for `html2rss-web`:
 
 ```bash
 mkdir html2rss-web
@@ -42,28 +41,26 @@ cd html2rss-web
 
 ### Step 2: Create a Minimal Configuration File
 
-Create a file called `docker-compose.yml` in your new folder. Start with the minimal local stack:
+Create a file called `docker-compose.yml` in that folder and start with the minimal local stack:
 
 <MinimalDockerCompose />
 
-Add update automation such as Watchtower later, after the first run works.
-
-### Step 3: Download the Feed List
+Add update automation later, after the first run works.
 
-html2rss-web needs a list of feeds to work with. Download our pre-made list:
+### Step 3: Download `feeds.yml`
 
-**Download the feeds.yml file:**
+Download the default `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:
+- **Browser:** Right-click [this link](https://raw.githubusercontent.com/html2rss/html2rss-web/master/config/feeds.yml) and save it as `feeds.yml`
+- **Terminal:**
 
 ```bash
 curl https://raw.githubusercontent.com/html2rss/html2rss-web/master/config/feeds.yml -o feeds.yml
 ```
 
 ### Step 4: Start html2rss-web
 
-Open a terminal in your html2rss-web folder and run:
+Run:
 
 ```bash
 docker compose up -d
@@ -73,27 +70,29 @@ docker compose up -d
 
 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
+1. Open `http://localhost:3000`
+2. Confirm the web interface loads
+3. Paste a page URL into `Create a feed`
+4. Generate a feed URL
+5. Copy that feed URL into your reader or open it directly
 
-If you see the interface, the setup worked.
+If that works, the deployment, interface, and feed-generation path are working together.
 
 ## What To Do First
 
-1. Open one included feed from the list
-2. Copy the RSS URL into your reader
-3. Confirm you can subscribe successfully
+Start with the web interface itself:
 
-That proves the web app, feed config file, and request pipeline are all working together.
+1. create one feed from a known page URL
+2. open or copy the generated feed URL
+3. confirm your reader can subscribe successfully
 
-<AutoGenerationOptional />
+That proves the core path before you invest in deeper customization.
 
----
+<AutoGenerationOptional />
 
 ## Next Steps
 
-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 workflow
-3. **[Create Custom Feeds](/creating-custom-feeds)** - Write and test your own configs
-4. **[Need help?](/troubleshooting/troubleshooting)** - Troubleshoot startup and extraction problems
+1. **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)**: understand the web UI creation path in more detail
+2. **[Create Custom Feeds](/creating-custom-feeds)**: write your own configs when you need reviewable extraction rules
+3. **[Browse working feed examples](/feed-directory/)**: compare outputs and existing configs
+4. **[Need help?](/troubleshooting/troubleshooting)**: troubleshoot startup and extraction problems
diff --git a/src/content/docs/web-application/how-to/use-automatic-feed-generation.mdx b/src/content/docs/web-application/how-to/use-automatic-feed-generation.mdx
@@ -1,15 +1,15 @@
 ---
 title: "Use automatic feed generation"
-description: "This feature lets you create RSS feeds automatically - just enter a website URL and html2rss-web figures out the rest!"
+description: "Enable the web UI flow that generates a feed directly from a page URL."
 ---
 
-This feature lets you create RSS feeds automatically - just enter a website URL and html2rss-web figures out the rest!
+Automatic feed generation is the direct web-interface workflow: paste a page URL, create a feed, then copy the generated feed URL.
 
 > **Note:** This feature is disabled by default for security reasons.
 
 ## How to Enable It
 
-1. **Edit your `docker-compose.yml` file** and uncomment these lines:
+Edit your `docker-compose.yml` and enable the automatic generation environment variables:
 
 ```yaml
 environment:
@@ -19,7 +19,7 @@ environment:
   AUTO_SOURCE_ALLOWED_ORIGINS: 127.0.0.1:3000
 ```
 
-2. **Restart html2rss-web:**
+Then restart:
 
 ```bash
 docker compose down
@@ -28,16 +28,26 @@ docker compose up -d
 
 ## How to Use It
 
-1. **Open the auto-source page:** Go to `http://localhost:3000/auto_source/`
-2. **Enter your credentials** (the username and password you set above)
-3. **Enter a website URL** and click "Generate"
-4. **Get your RSS feed!** html2rss-web will create a feed automatically
+1. Open your instance at `http://localhost:3000`
+2. Paste a page URL into `Create a feed`
+3. Submit the form
+4. If access is required, provide the configured access token
+5. Copy the generated feed URL or open it directly
 
-**That's it!** No configuration files needed - html2rss-web does all the work for you.
+## What Success Looks Like
+
+When the flow works, you should see:
+
+- a generated feed URL
+- a copy action
+- an open-feed action
+- a preview of recent entries when available
+
+That is enough to confirm the endpoint is live.
 
 ## When to Stop and Switch
 
-Automatic feed generation is a fast first try, not the final answer for every site.
+Automatic feed generation is the fast first pass, not the final answer for every site.
 
 Move on to [Creating Custom Feeds](/creating-custom-feeds) when:
 
diff --git a/src/content/docs/web-application/index.mdx b/src/content/docs/web-application/index.mdx
