docs: funnel through quickstart and consolidate

[gildesmarais]

This pull request reorganizes and clarifies the documentation structure and navigation, updates environment and deployment examples for consistency and security, and refines terminology and onboarding flows to improve the user experience. The changes focus on making the docs more intuitive, aligning navigation and links, and simplifying deployment instructions.

Documentation structure and navigation:

• Replaced "How-to" and "Tutorials" sections with a unified "Guides" section in the sidebar for both the web application and Ruby gem, and updated sidebar links to consistently use trailing slashes for better navigation. [1] [2]
• Updated and added redirects in astro.config.mjs to align old URLs (e.g., /how-to/, /tutorials/) with the new guides structure and naming conventions.

Terminology and onboarding improvements:

• Added a "User Journey Funnel" section to AGENTS.md to define clear onboarding phases and enforce consistent terminology (e.g., always use "Feed Directory" instead of "catalog").
• Clarified introductory and fallback paths in docs, emphasizing the main onboarding flow and updating references to new URLs and terms throughout the documentation. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10]

Deployment and environment example updates:

• Simplified and clarified the example .env file, focusing on required secrets and tokens, and updated comments for security and usability.
• Updated the example docker-compose.yml to remove the Caddy and Watchtower services from the minimal deployment, set required environment variables explicitly, and align with the new .env structure.

Code and snippet consistency:

• Updated deployment code snippets to match the new environment variable names and removed unnecessary services (e.g., browserless) from minimal and production examples. [1] [2] [3] [4] [5]

Content cleanup:

• Removed the unused get-involved/discussions.mdx page to streamline the documentation.

Quickstart introduced in html2rss/html2rss-web#976

[Copilot]

Pull request overview

Refactors the documentation onboarding for html2rss-web to center the “page URL → token → generated feed” quickstart flow, and reorganizes content from legacy “how-to” paths into “guides”, with updated deployment, monitoring, and env-var references.

Changes:

• Rebuilds the primary onboarding path around quickstart Compose + demo token + first generated feed, then handoff to deployment/production.
• Reorganizes docs IA (How-to → Guides), updates cross-links/redirects, and expands reference material (monitoring, versioning, env vars).
• Updates deployment snippets/components and examples to match the simplified runtime expectations (HTML2RSS_ACCESS_TOKEN, Botasaurus-first).

Reviewed changes

Copilot reviewed 39 out of 44 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/content/docs/web-application/reference/versioning-and-releases.mdx	Updates Watchtower link target to the Deployment page.
src/content/docs/web-application/reference/monitoring.mdx	Adds production-token warning and refines probe descriptions.
src/content/docs/web-application/reference/index.mdx	Adds reference navigation links (monitoring/versioning) and adjusts schema wording.
src/content/docs/web-application/reference/env-variables.mdx	Updates env var reference to include HTML2RSS_ACCESS_TOKEN and revised defaults.
src/content/docs/web-application/index.mdx	Rewrites Web App overview, recommended flow, and guide links.
src/content/docs/web-application/how-to/use-automatic-feed-generation.mdx	Removes legacy how-to page (superseded by guides).
src/content/docs/web-application/how-to/automatic-updates.mdx	Removes legacy how-to page (Watchtower moved under Deployment).
src/content/docs/web-application/guides/use-the-feed-directory.mdx	Renames/reframes “included configs” as Feed Directory usage.
src/content/docs/web-application/guides/use-automatic-feed-generation.mdx	Adds new guide describing the auto-generation workflow.
src/content/docs/web-application/guides/setup-for-development.mdx	Adds a development setup guide (Docker + local Ruby).
src/content/docs/web-application/getting-started.mdx	Replaces “included feeds first” with quickstart demo + token + generated feed path.
src/content/docs/web-application/deployment.mdx	Reorients production setup around HTML2RSS_ACCESS_TOKEN and updated service stack.
src/content/docs/troubleshooting/troubleshooting.mdx	Updates troubleshooting guidance for new auth/health patterns and Botasaurus-first setup.
src/content/docs/ruby-gem/tutorials/your-first-feed.mdx	Fixes internal link trailing slash for reference path.
src/content/docs/ruby-gem/tutorials/index.mdx	Removes tutorials overview page (points users directly at first tutorial).
src/content/docs/ruby-gem/reference/wordpress-api.mdx	Updates link to moved “scraping JSON” guide path.
src/content/docs/ruby-gem/reference/headers.mdx	Updates link to moved “dynamic parameters” guide path.
src/content/docs/ruby-gem/installation.mdx	Updates links to trailing-slash canonical routes.
src/content/docs/ruby-gem/index.mdx	Updates entry-point links and section naming (Guides/Reference).
src/content/docs/ruby-gem/guides/scraping-json.mdx	Adds a new guide for JSON→XML scraping behavior and examples.
src/content/docs/ruby-gem/guides/managing-feed-configs.mdx	Adds a new guide for organizing YAML feed configs and usage examples.
src/content/docs/ruby-gem/guides/handling-dynamic-content.mdx	Updates internal links to new guide/reference routes.
src/content/docs/ruby-gem/guides/dynamic-parameters.mdx	Updates related-topic links to new guide/reference routes.
src/content/docs/ruby-gem/guides/custom-http-requests.mdx	Updates related-topic links to new guide/reference routes.
src/content/docs/ruby-gem/guides/backward-compatibility.mdx	Adds a new guide describing renamed/legacy attribute behavior.
src/content/docs/ruby-gem/guides/advanced-features.mdx	Adds a new “advanced features” guide with performance/monitoring notes.
src/content/docs/ruby-gem/guides/advanced-content-extraction.mdx	Updates anchor links to selector extractor/post-processor sections.
src/content/docs/index.mdx	Rewrites homepage onboarding into the 3-phase funnel and updates deep-dive links.
src/content/docs/getting-started.mdx	Updates global Getting Started routing/shortcuts to the new guides structure.
src/content/docs/get-involved/sponsoring.mdx	Removes standalone sponsoring page (replaced by links from Get Involved index).
src/content/docs/get-involved/self-hosting.mdx	Removes redundant self-hosting routing page (content now lives in Web App docs).
src/content/docs/get-involved/issues-and-features.mdx	Removes redundant issues/features page (replaced by direct GitHub links).
src/content/docs/get-involved/index.mdx	Expands Get Involved overview with clearer contribution paths and direct links.
src/content/docs/get-involved/discussions.mdx	Removes redundant discussions page (replaced by direct GitHub Discussions link).
src/content/docs/get-involved/contributing.mdx	Updates links to new canonical routes.
src/content/docs/feed-directory/index.mdx	Clarifies Feed Directory as fallback/catalog and links to new deployment route.
src/content/docs/creating-custom-feeds.mdx	Updates links to new canonical routes and moved guides.
src/content/docs/common-use-cases.mdx	Updates quickstart links to new guide routes.
src/components/docs/DockerComposeSnippet.astro	Updates Compose snippet variants (removes Browserless, adds HTML2RSS_ACCESS_TOKEN, adjusts Watchtower scope).
src/components/docs/AutoGenerationOptional.astro	Updates guidance copy/links to new guides route.
examples/deployment/docker-compose.yml	Simplifies deployment example env vars/services to match new primary workflow.
examples/deployment/.env	Updates example env file to new token model and optional health token.
astro.config.mjs	Adds redirects and updates sidebar links and sections (Guides vs How-to).
AGENTS.md	Adds explicit “user journey funnel” authoring rules and terminology constraints.

Comments suppressed due to low confidence (1)

src/content/docs/ruby-gem/guides/advanced-content-extraction.mdx:14

• These links include a trailing slash in the fragment (#extractors/, #post-processors/). The corresponding heading ids in selectors.mdx are extractors and post-processors (no trailing slash), so these anchors won’t resolve. Remove the trailing slash from the fragments.