docs(onboarding): make docker the default path#1088
Conversation
There was a problem hiding this comment.
Pull request overview
This PR updates the documentation onboarding flow to make running html2rss-web locally with Docker the default starting path, and guides users toward included configs first before moving to automatic generation or custom YAML.
Changes:
- Reworks the docs landing pages and web-app overview to emphasize “Docker → included configs → (optional) auto-generation → custom configs”.
- Adds “success criteria” / “when to move on” sections to included-config and auto-generation docs.
- Introduces reusable docs components for a minimal Docker Compose snippet and an “auto-generation is optional” aside, and updates the Starlight sidebar ordering.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| src/content/docs/web-application/index.mdx | Reframes the web app overview and adds a recommended flow. |
| src/content/docs/web-application/how-to/use-included-configs.mdx | Adds success criteria and guidance on when to switch to custom configs. |
| src/content/docs/web-application/how-to/use-automatic-feed-generation.mdx | Adds guidance on when to stop using auto-generation and move to custom configs. |
| src/content/docs/web-application/getting-started.mdx | Makes Docker the primary setup path and embeds new reusable components. |
| src/content/docs/index.mdx | Updates the main docs homepage onboarding to point to Docker-based setup first. |
| src/content/docs/getting-started.mdx | Converts the top-level “Getting Started” into a pointer to the canonical Docker onboarding flow. |
| src/content/docs/creating-custom-feeds.mdx | Adds workflow guidance and cross-links to included/auto-generation paths. |
| src/components/docs/MinimalDockerCompose.astro | New: reusable YAML snippet renderer for a minimal compose file. |
| src/components/docs/AutoGenerationOptional.astro | New: reusable aside clarifying auto-generation is optional. |
| astro.config.mjs | Updates sidebar navigation to surface Getting Started and Custom Feeds earlier. |
You can also share your feedback on Copilot code review. Take the survey.
| @@ -0,0 +1,33 @@ | |||
| --- | |||
| import Code from "astro/components/Code.astro"; | |||
There was a problem hiding this comment.
astro/components/Code.astro is a low-level Astro component import and may not match Starlight’s code-block styling (and can be brittle across Astro versions). Prefer using Starlight’s exported Code component (or a plain fenced code block) so this snippet renders consistently with the rest of the docs site.
| import Code from "astro/components/Code.astro"; | |
| import { Code } from "@astrojs/starlight/components"; |
| 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 |
There was a problem hiding this comment.
The compose snippet hardcodes BROWSERLESS_IO_API_TOKEN to a fixed value. Even though ports are bound to localhost in this example, readers may copy/paste it into non-local deployments; using a placeholder (or showing an env-substitution like ${BROWSERLESS_IO_API_TOKEN}) reduces the chance of accidentally deploying with a known token.
| environment: | ||
| PORT: 3001 | ||
| CONCURRENT: 10 | ||
| TOKEN: 6R0W53R135510`; |
There was a problem hiding this comment.
The Browserless TOKEN is also hardcoded to a fixed value. Consider replacing it with a placeholder and explicitly noting it must match BROWSERLESS_IO_API_TOKEN in the html2rss-web container to avoid confusion and insecure copy/paste defaults.
No description provided.