docs(web): align deployment and operator guidance

[gildesmarais]

This pull request introduces significant improvements to the documentation and deployment guidance for the html2rss.github.io repository. The main focus is on clarifying repository scope and cross-repo boundaries, modernizing deployment examples, enforcing consistent documentation authoring practices, and improving the accuracy and usability of self-hosting and contributing guides.

Key changes:

Repository Guidelines and Authoring Practices

• Added a comprehensive AGENTS.md file outlining repository scope, ownership, cross-repo contracts, generated artifact handling, verification flows, and documentation authoring rules (e.g., always use the <Code> component for code snippets).
• Updated all documentation files to use the <Code> component from @astrojs/starlight/components instead of triple-backtick code blocks or legacy imports, ensuring consistent code rendering across the site [1] [2] [3].

Deployment and Environment Configuration

• Modernized Docker Compose examples in both documentation and code snippets:
  • Changed the main service name from html2rss to html2rss-web.
  • Added robust environment variable handling, including required secrets and tokens.
  • Updated service restart policies and port mappings for production readiness.
  • Improved Watchtower configuration for automatic updates [1] [2] [3] [4] [5].
• Provided a new example .env file with clear documentation for required and optional settings.

Self-Hosting and Contributing Documentation

• Overhauled the self-hosting guide to clarify that deployment, Docker, and advanced configuration documentation now live in the html2rss-web docs, and provided a clear, concise recommended path for new users.
• Improved the contributing guide with updated code snippet rendering and clearer instructions for testing custom configs.

Quick Setup and README Updates

• Updated the README.md to clarify the setup process, including the need to refresh generated feed data and the correct Codespaces link for this repository.

Documentation Usability and Accuracy

• Revised all code and YAML examples in the custom feed creation guide to use the <Code> component, improving readability and consistency [1] [2] [3] [4] [5] [6].

These changes collectively improve contributor onboarding, deployment reliability, and the clarity and maintainability of the documentation for both new and experienced users.

[Copilot]

Pull request overview

Aligns html2rss-web operator/deployment documentation around the current health endpoints, token-gated generation model, and integration entry points (OpenAPI, API root metadata, config schema).

Changes:

• Reworks monitoring/deployment guidance to use /api/v1/health/* probes and bearer-token authenticated checks.
• Updates reference/index + web-application landing pages with integration entry points (OpenAPI, /api/v1, env vars, config schema).
• Expands automatic generation docs with clearer prerequisites, strategy behavior, troubleshooting, and URL-surface guidance; refreshes Docker Compose snippets/examples accordingly.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
src/content/docs/web-application/reference/monitoring.mdx	Documents new health endpoints and authenticated probe usage.
src/content/docs/web-application/reference/index.mdx	Adds integration entry points (OpenAPI, API root, env ref, schema).
src/content/docs/web-application/reference/env-variables.mdx	Updates supported env var list to the current html2rss-web set.
src/content/docs/web-application/index.mdx	Clarifies access-controlled generation and surfaces OpenAPI/API entry points.
src/content/docs/web-application/how-to/use-automatic-feed-generation.mdx	Adds prerequisites, strategy behavior, troubleshooting, and guidance for auto flow.
src/content/docs/web-application/how-to/deployment.mdx	Refocuses production guidance on scope selection, token-based ops, and OpenAPI.
src/content/docs/web-application/getting-started.mdx	Emphasizes included-feed validation before enabling generation; notes OpenAPI.
src/content/docs/troubleshooting/troubleshooting.mdx	Updates web-app troubleshooting to token-based auth + new health endpoints.
src/content/docs/ruby-gem/reference/strategy.mdx	Adds practical strategy selection + Browserless troubleshooting notes.
src/content/docs/ruby-gem/reference/cli-reference.mdx	Adds auto URL-surface guidance, failure taxonomy, and Browserless diagnostics.
src/content/docs/ruby-gem/index.mdx	Points to the JSON Schema contract + schema/validate CLI entry points.
src/content/docs/get-involved/self-hosting.mdx	Converts to a routing page pointing to canonical html2rss-web docs.
src/components/docs/DockerComposeSnippet.astro	Updates Compose snippets (env var requirements, Caddy target, Watchtower).
examples/deployment/docker-compose.yml	Renames service to html2rss-web and updates Caddy upstream port/name.

[Copilot]

Pull request overview

Copilot reviewed 39 out of 41 changed files in this pull request and generated 5 comments.