docs(docs): batch low-risk review cleanups

Group the unresolved review items that improve docs consistency without changing onboarding behavior.\n\nAdopt the shared Code component on the reviewed snippets, tighten a few over-explained passages, and apply the direct copy suggestions that clarify terminology and intent. Keep the blocked product-doc issues for a later pass so this commit stays low risk and easy to review.

Author: gildesmarais

src/content/docs/creating-custom-feeds.mdx

@@ -6,6 +6,7 @@ sidebar:
 ---
 
 import { Aside } from "@astrojs/starlight/components";
+import Code from "astro/components/Code.astro";
 
 When auto-sourcing isn't enough, you can write your own configuration files to create custom RSS feeds for any website. This guide shows you how to take full control with YAML configs.
 
@@ -167,13 +168,14 @@ Some sites need a little more request budget than the defaults.
 - Use `--max-redirects` when the site bounces through several canonicalization or tracking redirects before the real page loads.
 - Use `--max-requests` when your config needs more than one request, for example pagination or other follow-up fetches.
 
-```bash
-html2rss feed your-config.yml --max-redirects 10
+<Code
+  code={`html2rss feed your-config.yml --max-redirects 10
 html2rss feed your-config.yml --max-requests 5
-html2rss auto https://example.com/blog --max-redirects 10 --max-requests 5
-```
+html2rss auto https://example.com/blog --max-redirects 10 --max-requests 5`}
+  lang="bash"
+/>
 
-Keep these values as low as possible. If a site only needs one extra redirect, prefer `--max-redirects 4` over a much larger number.
+Keep these values tight. Raise them only when the site proves it needs more.
 
 ## Add It To html2rss-web
 

src/content/docs/getting-started.mdx

@@ -5,6 +5,8 @@ sidebar:
   order: 1
 ---
 
+import Code from "astro/components/Code.astro";
+
 This page points to the main onboarding flow.
 
 ## Start Here
@@ -30,14 +32,10 @@ That guide is the canonical setup flow for:
 
 If you are working directly with the gem instead of `html2rss-web`, start with:
 
-```bash
-html2rss auto https://example.com/blog
-```
+<Code code={`html2rss auto https://example.com/blog`} lang="bash" />
 
 If the target site is unusually redirect-heavy or needs extra follow-up requests, the CLI also supports:
 
-```bash
-html2rss auto https://example.com/blog --max-redirects 10 --max-requests 5
-```
+<Code code={`html2rss auto https://example.com/blog --max-redirects 10 --max-requests 5`} lang="bash" />
 
 For config-driven runs, the same flags are available on `html2rss feed`.

src/content/docs/ruby-gem/how-to/custom-http-requests.mdx

@@ -3,7 +3,9 @@ title: "Custom HTTP Requests"
 description: "Learn how to customize HTTP requests with custom headers, authentication, and API interactions for html2rss."
 ---
 
-Some websites require custom HTTP headers, authentication, or other request settings to access their content. `html2rss` lets you customize requests for those cases.
+import Code from "astro/components/Code.astro";
+
+Some sites only work when requests carry the headers, tokens, or cookies your browser uses. `html2rss` supports those cases without changing the rest of your feed workflow.
 
 Keep this structure in mind:
 
@@ -25,8 +27,8 @@ You might need custom HTTP requests when:
 
 Add a `headers` section to your feed configuration. This example is a complete, valid config:
 
-```yaml
-headers:
+<Code
+  code={`headers:
   User-Agent: "Mozilla/5.0 (compatible; html2rss/1.0)"
   Authorization: "Bearer YOUR_API_TOKEN"
   Accept: "application/json"
@@ -38,15 +40,16 @@ selectors:
   title:
     selector: "title"
   url:
-    selector: "url"
-```
+    selector: "url"`}
+  lang="yaml"
+/>
 
 ## Request Controls
 
 Request budgets are configured under `request`, not as top-level keys:
 
-```yaml
-headers:
+<Code
+  code={`headers:
   User-Agent: "Mozilla/5.0 (compatible; html2rss/1.0)"
 request:
   max_redirects: 5
@@ -60,8 +63,9 @@ selectors:
     selector: h2
   url:
     selector: a
-    extractor: href
-```
+    extractor: href`}
+  lang="yaml"
+/>
 
 - `request.max_redirects` limits redirect hops
 - `request.max_requests` limits the total request budget for the feed build

src/content/docs/ruby-gem/how-to/handling-dynamic-content.mdx

@@ -3,6 +3,8 @@ title: Handling Dynamic Content
 description: "Learn how to handle JavaScript-heavy websites and dynamic content with html2rss. Use browserless strategy for sites that load content dynamically."
 ---
 
+import Code from "astro/components/Code.astro";
+
 Some websites load their content dynamically using JavaScript. The default `html2rss` strategy might not see this content.
 
 ## Solution
@@ -11,8 +13,8 @@ Use the [`browserless` strategy](/ruby-gem/reference/strategy) to render JavaScr
 
 Keep the strategy at the top level and put request-specific options under `request`:
 
-```yaml
-strategy: browserless
+<Code
+  code={`strategy: browserless
 request:
   max_redirects: 5
   max_requests: 6
@@ -29,8 +31,9 @@ selectors:
     selector: h2
   url:
     selector: a
-    extractor: href
-```
+    extractor: href`}
+  lang="yaml"
+/>
 
 ## When to Use Browserless
 

src/content/docs/ruby-gem/reference/cli-reference.mdx

@@ -24,7 +24,7 @@ html2rss auto https://example.com/articles
 # Force browserless for JavaScript-heavy pages
 html2rss auto https://example.com/app --strategy browserless
 
-# Override request budgets at runtime
+# Set custom request budgets
 html2rss auto https://example.com/app --strategy browserless --max-redirects 5 --max-requests 6
 
 # Hint the item selector while keeping auto enhancement

src/content/docs/ruby-gem/reference/strategy.mdx

@@ -8,7 +8,7 @@ The `strategy` key defines how `html2rss` fetches a website's content.
 - **`faraday`** (default): Makes a direct HTTP request. It is fast but does not execute JavaScript.
 - **`browserless`**: Renders the website in a headless Chrome browser, which is necessary for JavaScript-heavy sites.
 
-`strategy` stays a top-level config key. Request-specific controls now live under `request`.
+`strategy` is a top-level config key. Request-specific controls live under `request`.
 
 ## `browserless`
 

src/content/docs/ruby-gem/reference/wordpress-api.mdx

@@ -67,22 +67,22 @@ If `content.rendered` is blank, the scraper falls back to `excerpt.rendered`.
 
 - The scraper uses the shared request session, so it participates in the same request safety model as the rest of the feed build.
 - It resolves relative API links against `channel.url`.
-- It currently stores WordPress category IDs as strings because category-name resolution is not implemented yet.
-- It currently does not resolve `featured_media` into an image URL.
+- It keeps WordPress category IDs as strings; category-name resolution is not implemented yet.
+- It does not resolve `featured_media` into an image URL.
 
 ## When To Use It
 
 Prefer `wordpress_api` when:
 
 - The page is clearly powered by WordPress
 - The REST API is public
-- You want more stable extraction than CSS selectors or heuristic HTML scraping
+- You want a more stable source than CSS selectors or heuristic HTML scraping
 
 Prefer manual selectors when:
 
 - The site blocks or customizes the API heavily
 - You need fields that are not exposed by the post endpoint
-- You want complete control over item filtering or presentation
+- You need full control over filtering or presentation
 
 ## Related Docs
 

src/content/docs/web-application/how-to/deployment.mdx

@@ -5,7 +5,7 @@ description: "Deploy html2rss-web to production with Docker. Learn best practice
 
 import DockerComposeSnippet from "../../../../components/docs/DockerComposeSnippet.astro";
 
-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.
+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, downloading the reference compose file, and confirming the application locally—steps we will build upon here.