From e1b8686636eeecabb96d4ff4a8564d42afd623b1 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 21 Mar 2026 13:33:06 +0100
Subject: [PATCH] docs: simplify self-hosted web onboarding

---
 examples/deployment/docker-compose.yml        |  39 +++++++
 .../docs/AutoGenerationOptional.astro         |   6 +-
 .../docs/DockerComposeSnippet.astro           |  96 ++++++++++++++++
 .../docs/MinimalDockerCompose.astro           |  32 +-----
 src/content/docs/getting-started.mdx          |  16 +--
 src/content/docs/index.mdx                    | 108 ++++++------------
 .../docs/web-application/getting-started.mdx  |  75 ++++++------
 .../web-application/how-to/deployment.mdx     |  74 ++----------
 .../how-to/use-automatic-feed-generation.mdx  |  36 +++---
 .../how-to/use-included-configs.mdx           |  20 ++--
 src/content/docs/web-application/index.mdx    |  30 ++---
 .../reference/versioning-and-releases.mdx     |   4 +-
 src/data/docker.ts                            |   6 +
 13 files changed, 287 insertions(+), 255 deletions(-)
 create mode 100644 examples/deployment/docker-compose.yml
 create mode 100644 src/components/docs/DockerComposeSnippet.astro
 create mode 100644 src/data/docker.ts

diff --git a/examples/deployment/docker-compose.yml b/examples/deployment/docker-compose.yml
new file mode 100644
index 00000000..5b98fa66
--- /dev/null
+++ b/examples/deployment/docker-compose.yml
@@ -0,0 +1,39 @@
+services:
+  html2rss:
+    image: html2rss/web:latest
+    env_file: .env
+
+  caddy:
+    image: caddy:2-alpine
+    depends_on:
+      - html2rss
+    command:
+      - caddy
+      - reverse-proxy
+      - --from
+      - ${CADDY_HOST}
+      - --to
+      - html2rss:3000
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - caddy_data:/data
+
+  watchtower:
+    image: containrrr/watchtower
+    depends_on:
+      - html2rss
+      - caddy
+    command:
+      - --cleanup
+      - --interval
+      - "300"
+      - html2rss
+      - caddy
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    restart: unless-stopped
+
+volumes:
+  caddy_data:
diff --git a/src/components/docs/AutoGenerationOptional.astro b/src/components/docs/AutoGenerationOptional.astro
index 35039fc9..982682bb 100644
--- 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/components/docs/DockerComposeSnippet.astro b/src/components/docs/DockerComposeSnippet.astro
new file mode 100644
index 00000000..e2706e43
--- /dev/null
+++ b/src/components/docs/DockerComposeSnippet.astro
@@ -0,0 +1,96 @@
+---
+import Code from "astro/components/Code.astro";
+import { browserlessImage, caddyImage, watchtowerImage, webImage } from "../../data/docker";
+
+interface Props {
+  variant: "minimal" | "productionCaddy" | "secure" | "watchtower" | "resourceGuardrails";
+}
+
+const { variant } = Astro.props;
+
+const snippets: Record<Props["variant"], string> = {
+  minimal: `services:
+  html2rss-web:
+    image: ${webImage}
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:4000:4000"
+    environment:
+      RACK_ENV: production
+      PORT: 4000
+      HTML2RSS_SECRET_KEY: your-generated-secret-key
+      HEALTH_CHECK_TOKEN: your-health-check-token
+      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:4002
+      BROWSERLESS_IO_API_TOKEN: your-browserless-token
+
+  browserless:
+    image: "${browserlessImage}"
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:4002:4002"
+    environment:
+      PORT: 4002
+      CONCURRENT: 10
+      TOKEN: your-browserless-token`,
+  productionCaddy: `services:
+  caddy:
+    image: ${caddyImage}
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - caddy_data:/data
+    command:
+      - caddy
+      - reverse-proxy
+      - --from
+      - \${CADDY_HOST}
+      - --to
+      - html2rss:3000
+  html2rss:
+    image: ${webImage}
+    env_file: .env
+
+volumes:
+  caddy_data:`,
+  secure: `services:
+  html2rss:
+    image: ${webImage}
+    environment:
+      RACK_ENV: production
+      LOG_LEVEL: warn
+      HEALTH_CHECK_USERNAME: your-secure-username
+      HEALTH_CHECK_PASSWORD: your-very-secure-password
+      BASE_URL: https://yourdomain.com`,
+  watchtower: `services:
+  watchtower:
+    image: ${watchtowerImage}
+    depends_on:
+      - html2rss
+      - caddy
+    command:
+      - --cleanup
+      - --interval
+      - "300"
+      - html2rss
+      - caddy
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    restart: unless-stopped`,
+  resourceGuardrails: `services:
+  html2rss:
+    image: ${webImage}
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: "0.5"
+        reservations:
+          memory: 256M
+          cpus: "0.25"`,
+};
+
+const code = snippets[variant];
+---
+
+<Code code={code} lang="yaml" />
diff --git a/src/components/docs/MinimalDockerCompose.astro b/src/components/docs/MinimalDockerCompose.astro
index ebc0001c..9eb6aeb0 100644
--- a/src/components/docs/MinimalDockerCompose.astro
+++ b/src/components/docs/MinimalDockerCompose.astro
@@ -1,33 +1,5 @@
 ---
-import Code from "astro/components/Code.astro";
-
-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`;
+import DockerComposeSnippet from "./DockerComposeSnippet.astro";
 ---
 
-<Code code={code} lang="yaml" />
+<DockerComposeSnippet variant="minimal" />
diff --git a/src/content/docs/getting-started.mdx b/src/content/docs/getting-started.mdx
index f5e2a871..c3874cfe 100644
--- 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 a working included feed from your self-hosted instance, and decide when to enable automatic generation or move to custom configs."
 sidebar:
   order: 1
 ---
@@ -16,15 +16,17 @@ 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
+- opening a first included 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
+- **[Browse working feed examples](/feed-directory/)**: see what successful outputs look like
+- **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)**: enable direct feed creation from a page URL when you want that workflow
+- **[Create Custom Feeds](/creating-custom-feeds)**: write configs when you need more control
+- **[Troubleshooting Guide](/troubleshooting/troubleshooting)**: fix startup or extraction problems
 
 ## Using the Ruby CLI
 
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
index 349bccae..8374aca4 100644
--- 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, verify a working included feed from your self-hosted instance, then consciously enable automatic generation or move to custom configs 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, verify a working included feed from your self-hosted instance, and only then decide whether to enable automatic generation or move to custom configs.
 
-## 🚀 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
+- opening a first included feed URL
+- deciding when to consciously enable automatic generation or move to 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 a built-in feed URL** from your own instance
+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 the included configs](/web-application/how-to/use-included-configs/)**: use real embedded feeds from your own instance
+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 an included feed to verify the deployment first.
+- Enable automatic generation only when you want the direct page-URL workflow and are ready to allow it on your self-hosted instance.
+- 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
index 12ac3428..2da2b129 100644
--- a/src/content/docs/web-application/getting-started.mdx
+++ b/src/content/docs/web-application/getting-started.mdx
@@ -1,6 +1,6 @@
 ---
 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 open your first included feed."
 sidebar:
   order: 2
 ---
@@ -8,15 +8,16 @@ sidebar:
 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 your instance can serve a working included feed.
 
 ## 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
+- `html2rss-web` running at `http://localhost:4000`
+- the web interface loading correctly
+- a first included feed URL you can copy into your reader
+- a clear path to either custom configs or more advanced setup
 
 ## Installation Guide
 
@@ -24,16 +25,14 @@ This guide walks you through a local Docker setup that gives you the most reliab
 
 ### 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,15 @@ 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
-
-html2rss-web needs a list of feeds to work with. Download our pre-made list:
+Add update automation later, after the first run works.
 
-**Download the feeds.yml file:**
+### Step 3: Start html2rss-web
 
-- **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
-
-Open a terminal in your html2rss-web folder and run:
+Run:
 
 ```bash
 docker compose up -d
@@ -73,27 +59,32 @@ 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:4000`
+2. Confirm the web interface loads
+3. Open one of the included feed URLs from your own instance:
+   - `http://localhost:4000/microsoft.com/azure-products.rss`
+   - `http://localhost:4000/phys.org/weekly.rss`
+   - `http://localhost:4000/softwareleadweekly.com/issues.rss`
+4. Confirm the feed opens
+5. Copy that feed URL into your reader
 
-If you see the interface, the setup worked.
+If that works, the deployment, static feed path, and reader subscription 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 an included config from your own instance:
 
-That proves the web app, feed config file, and request pipeline are all working together.
+1. open a known included feed URL
+2. copy that feed URL into your reader
+3. confirm your reader can subscribe successfully
 
-<AutoGenerationOptional />
+That proves the core path before you invest in automatic generation or custom configs.
 
----
+<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 the included configs](/web-application/how-to/use-included-configs/)**: understand how built-in feed paths work
+2. **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)**: enable direct feed creation from page URLs when you want that workflow
+3. **[Create Custom Feeds](/creating-custom-feeds)**: write your own configs when you need reviewable extraction rules
+4. **[Need help?](/troubleshooting/troubleshooting)**: troubleshoot startup and extraction problems
diff --git a/src/content/docs/web-application/how-to/deployment.mdx b/src/content/docs/web-application/how-to/deployment.mdx
index 20116856..8a8cbea4 100644
--- a/src/content/docs/web-application/how-to/deployment.mdx
+++ b/src/content/docs/web-application/how-to/deployment.mdx
@@ -3,9 +3,11 @@ title: "Deployment & Production"
 description: "Deploy html2rss-web to production with Docker. Learn best practices for hosting public instances with security, monitoring, and reliability."
 ---
 
-html2rss-web ships on Docker Hub, so you can launch it wherever Docker runs. Start with the official [`docker-compose.yml`](https://github.com/html2rss/html2rss-web/blob/master/docker-compose.yml) from the [Installation Guide](/web-application/getting-started) as your baseline.
+import DockerComposeSnippet from "../../../../components/docs/DockerComposeSnippet.astro";
 
-If you have not yet created a local instance, complete the [Getting Started guide](/web-application/getting-started) first. It walks through the one-time project directory setup, downloading the reference compose file, and confirming the application locally—steps we will build upon here.
+html2rss-web ships on Docker Hub, so you can launch this self-hosted service wherever Docker runs. Start with the official [`docker-compose.yml`](https://github.com/html2rss/html2rss-web/blob/master/docker-compose.yml) from the [Installation Guide](/web-application/getting-started) as your baseline.
+
+If you have not yet created a local instance, complete the [Getting Started guide](/web-application/getting-started) first. It walks through the one-time project directory setup, creating a minimal compose file, and confirming the application locally, which gives you the right baseline before exposing a self-hosted instance publicly.
 
 Already running html2rss-web on your workstation? Great! The sections below focus on what changes when you take that setup to production.
 
@@ -25,29 +27,7 @@ A reverse proxy accepts public HTTPS traffic, terminates TLS, and forwards reque
 
 Caddy handles certificates and redirects with almost no configuration.
 
-```yaml
-services:
-  caddy:
-    image: caddy:2-alpine
-    ports:
-      - "80:80"
-      - "443:443"
-    volumes:
-      - caddy_data:/data
-    command:
-      - caddy
-      - reverse-proxy
-      - --from
-      - ${CADDY_HOST}
-      - --to
-      - html2rss:3000
-  html2rss:
-    image: gilcreator/html2rss-web:latest
-    env_file: .env
-
-volumes:
-  caddy_data:
-```
+<DockerComposeSnippet variant="productionCaddy" />
 
 - Create a `.env` file beside your compose file with the following variables:
 
@@ -79,17 +59,7 @@ Harden the application before inviting other users:
 - Prefer environment files (`.env`) stored outside version control for secrets
 - Keep admin-only routes behind basic auth or IP restrictions in your proxy
 
-```yaml
-services:
-  html2rss:
-    image: gilcreator/html2rss-web:latest
-    environment:
-      RACK_ENV: production
-      LOG_LEVEL: warn
-      HEALTH_CHECK_USERNAME: your-secure-username
-      HEALTH_CHECK_PASSWORD: your-very-secure-password
-      BASE_URL: https://yourdomain.com
-```
+<DockerComposeSnippet variant="secure" />
 
 Store these variables in a `.env` file and reference it with `env_file:` as demonstrated in the Caddy example.
 
@@ -104,41 +74,13 @@ Keep the instance healthy once it is in production:
 
 ### Auto-update with Watchtower
 
-```yaml
-services:
-  watchtower:
-    image: containrrr/watchtower
-    depends_on:
-      - html2rss
-      - caddy
-    command:
-      - --cleanup
-      - --interval
-      - "300"
-      - html2rss
-      - caddy
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock
-    restart: unless-stopped
-```
+<DockerComposeSnippet variant="watchtower" />
 
 Check `docker compose logs watchtower` occasionally to confirm updates are applied.
 
 ### Resource Guardrails
 
-```yaml
-services:
-  html2rss:
-    image: gilcreator/html2rss-web:latest
-    deploy:
-      resources:
-        limits:
-          memory: 512M
-          cpus: "0.5"
-        reservations:
-          memory: 256M
-          cpus: "0.25"
-```
+<DockerComposeSnippet variant="resourceGuardrails" />
 
 Adjust the limits to match your host capacity. Increase memory if you process many large feeds.
 
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
index e19c379e..b7ed824e 100644
--- 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,25 +1,23 @@
 ---
 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 a standout `html2rss-web` feature: paste a page URL, create a feed, then copy the generated feed URL.
 
-> **Note:** This feature is disabled by default for security reasons.
+> **Note:** This feature is disabled by default. Enabling it should be a conscious decision on your self-hosted instance.
 
 ## How to Enable It
 
-1. **Edit your `docker-compose.yml` file** and uncomment these lines:
+Edit your `docker-compose.yml` and enable automatic feed generation:
 
 ```yaml
 environment:
   AUTO_SOURCE_ENABLED: "true"
-  AUTO_SOURCE_USERNAME: your-username
-  AUTO_SOURCE_PASSWORD: your-secure-password
-  AUTO_SOURCE_ALLOWED_ORIGINS: 127.0.0.1:3000
+  AUTO_SOURCE_ALLOWED_ORIGINS: 127.0.0.1:4000
 ```
 
-2. **Restart html2rss-web:**
+Then restart:
 
 ```bash
 docker compose down
@@ -28,16 +26,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:4000`
+2. Paste a page URL into `Create a feed`
+3. Submit the form
+4. If the instance requires access, provide a 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 self-hosted flow is working.
 
 ## 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/how-to/use-included-configs.mdx b/src/content/docs/web-application/how-to/use-included-configs.mdx
index 0d28df6a..d6143b05 100644
--- a/src/content/docs/web-application/how-to/use-included-configs.mdx
+++ b/src/content/docs/web-application/how-to/use-included-configs.mdx
@@ -1,15 +1,16 @@
 ---
 title: "Use the included configs"
-description: "html2rss-web comes with hundreds of ready-made feeds for popular websites! No configuration needed - just use the URLs."
+description: "Use the embedded html2rss-configs feed set from your own html2rss-web instance."
 ---
 
-html2rss-web comes with hundreds of ready-made feeds for popular websites! No configuration needed - just use the URLs.
+`html2rss-web` can serve the embedded `html2rss-configs` feed set directly from your own instance. This is the fastest path when you want a working feed without writing YAML first.
 
 ## How to Use Them
 
 1. **Find a feed** in the [Feed Directory](/feed-directory/)
-2. **Copy the URL** (it looks like `domainname.tld/whatever.rss`)
-3. **Add it to your feed reader** - paste the URL and you're done!
+2. **Set the Instance URL** to your own `html2rss-web` address
+3. **Open the local feed path** from your instance
+4. **Add it to your feed reader**
 
 ## What Success Looks Like
 
@@ -23,10 +24,10 @@ If that works, keep using included configs for that site. It is the lowest-maint
 
 ## Example
 
-If you see a config file named `example.com/news.yml`, you can access it at:
-`http://localhost:3000/example.com/news.rss`
+If you see a config file named `phys.org/weekly.yml`, you can access it at:
+`http://localhost:4000/phys.org/weekly.rss`
 
-Just replace `localhost:3000` with your html2rss-web address.
+Just replace `localhost:4000` with your own `html2rss-web` address.
 
 ## When to Move On
 
@@ -36,4 +37,7 @@ Use a custom config when:
 - the included feed misses fields you care about
 - you need a more specific page, section, or output format
 
-Next step: [Create Custom Feeds](/creating-custom-feeds)
+Next steps:
+
+- [Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/) when you want to create feeds directly from page URLs
+- [Create Custom Feeds](/creating-custom-feeds) when you need a reviewable config
diff --git a/src/content/docs/web-application/index.mdx b/src/content/docs/web-application/index.mdx
index c5826bb7..aa689b1c 100644
--- a/src/content/docs/web-application/index.mdx
+++ b/src/content/docs/web-application/index.mdx
@@ -1,34 +1,36 @@
 ---
 title: "Web Application"
-description: "html2rss-web is an easy-to-use web application that creates RSS feeds from any website. No coding required - just point, click, and get your RSS feed."
+description: "html2rss-web is the self-hosted web interface and feed server for running included feeds first, then enabling direct generation only when needed."
 sidebar:
   label: "Overview"
   order: 1
 ---
 
-`html2rss-web` is the recommended way to get started. Run it locally with Docker, use included feeds first, and move to automatic generation or custom configs only when you need more control.
+`html2rss-web` is the recommended way to get started. Run it locally with Docker, verify a working included feed from your own instance, and only then decide whether you need direct generation or custom configs.
 
 ## Get Started
 
 Start with **[Getting Started](/web-application/getting-started)** to:
 
 - run your own local instance
-- confirm a first successful feed
+- verify the web interface
+- open a first included feed URL
 - choose the right next step for your site
 
-## Key Features
+## What The Web App Gives You
 
-- **Stable URLs:** Provides stable URLs for feeds served from your own instance
-- **Included Feeds:** Start with many working configs out of the box
-- **Automatic Generation:** Try new sites quickly when the feature is enabled
-- **Custom Feeds:** Create and refine your own configs when you need more control
-- **Caching:** Handles request caching and sets HTTP headers
+- **Included feed catalog:** real embedded configs you can use immediately from your own deployment
+- **Web interface:** direct feed creation when you explicitly enable it
+- **Optional access control:** unlock custom generation with an access token when configured
+- **Config-based extension path:** move to custom feeds when you need reviewable rules
+- **Caching and HTTP handling:** shipped as part of the deployment
 
-The functionality of scraping websites and building the RSS feeds is provided by the Ruby gem [`html2rss`](https://github.com/html2rss/html2rss).
+The scraping and feed-building engine is provided by the Ruby gem [`html2rss`](https://github.com/html2rss/html2rss).
 
 ## Recommended Flow
 
-1. **[Getting Started](/web-application/getting-started)** - Run the app locally
-2. **[Use the included configs](/web-application/how-to/use-included-configs/)** - Confirm a working feed first
-3. **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)** - Try unsupported sites quickly
-4. **[Create Custom Feeds](/creating-custom-feeds)** - Build a stable custom setup when needed
+1. **[Getting Started](/web-application/getting-started)**: run the app locally
+2. **[Use the included configs](/web-application/how-to/use-included-configs/)**: start with embedded feed paths from your own instance
+3. **[Browse working feed examples](/feed-directory/)**: compare against existing outputs
+4. **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)**: enable direct page-URL conversion when you want that workflow
+5. **[Create Custom Feeds](/creating-custom-feeds)**: build a stable custom setup when needed
diff --git a/src/content/docs/web-application/reference/versioning-and-releases.mdx b/src/content/docs/web-application/reference/versioning-and-releases.mdx
index 63de78d2..903adff8 100644
--- a/src/content/docs/web-application/reference/versioning-and-releases.mdx
+++ b/src/content/docs/web-application/reference/versioning-and-releases.mdx
@@ -3,9 +3,11 @@ title: Versioning and releases
 description: Learn about versioning and release strategy for html2rss-web
 ---
 
+import { dockerHubRepository, dockerHubUrl } from "../../../../data/docker";
+
 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).
+For the latest commit passing GitHub CI/CD on the master branch, an updated Docker image will be pushed to <a href={dockerHubUrl}>Docker Hub: <code>{dockerHubRepository}</code></a>.
 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.
diff --git a/src/data/docker.ts b/src/data/docker.ts
new file mode 100644
index 00000000..dabe362c
--- /dev/null
+++ b/src/data/docker.ts
@@ -0,0 +1,6 @@
+export const dockerHubRepository = 'html2rss/web';
+export const dockerHubUrl = `https://hub.docker.com/r/${dockerHubRepository}`;
+export const webImage = `${dockerHubRepository}:latest`;
+export const browserlessImage = 'ghcr.io/browserless/chromium';
+export const caddyImage = 'caddy:2-alpine';
+export const watchtowerImage = 'containrrr/watchtower';