docs: migrate code blocks to Starlight Code and fix YAML indentation

Author: gildesmarais

AGENTS.md

@@ -0,0 +1,94 @@
+# Repository Guidelines
+
+## Scope and Ownership
+
+This repository (`html2rss.github.io/`) is the public docs and feed-directory site built with Astro/Starlight.
+Classify most work here as `docs`.
+
+What this repo owns:
+
+- docs content and navigation under `src/content/docs/`
+- docs-specific components and styling under `src/components/`
+- feed-directory presentation and client behavior
+- generated docs data consumed by the site (`src/data/configs.json`)
+
+What this repo does not own:
+
+- runtime extractor behavior and CLI semantics (`html2rss/`)
+- web API behavior and OpenAPI generation (`html2rss-web/`)
+- feed YAML catalog definitions (`html2rss-configs/`)
+
+When docs describe behavior from other repos, treat those repos as source-of-truth and update docs to match them.
+
+## Cross-Repo Contracts
+
+Before substantial edits, state cross-repo context in your notes:
+
+- Source-of-truth repo
+- Downstream consumer repo(s)
+- Whether this change needs coordinated follow-up outside `html2rss.github.io/`
+
+Common contracts:
+
+- Feed directory data comes from `html2rss-configs` via `bin/data-update`.
+- Ruby gem docs should match `html2rss` behavior and CLI output.
+- Web application docs should match `html2rss-web` behavior and published OpenAPI.
+
+If a cross-repo behavior changed but upstream is not updated yet, document the gap clearly instead of inventing new behavior.
+
+## Generated Artifacts
+
+Treat `src/data/configs.json` as generated.
+
+- Do not hand-edit it.
+- Regenerate with repo-native commands:
+  - `make update`
+  - or `bin/data-update` (after dependencies are installed)
+- `bin/data-update` reads packaged configs (from `html2rss-configs`) and writes `src/data/configs.json`.
+
+If a change only affects generated data, include the source change rationale in the PR description.
+
+## Build, Test, and Dev Commands
+
+Run commands from `html2rss.github.io/`:
+
+- `make setup` installs dependencies and refreshes generated data
+- `make dev` runs Astro locally
+- `make build` builds production output
+- `make lint` checks formatting
+- `make lintfix` applies formatting fixes
+- `make update` refreshes feed-directory data from packaged configs
+
+Preferred verification flow for docs/content changes:
+
+1. Run targeted check(s) first (`make lint` or `make build`).
+2. Run the broader check set before PR (`make lint` and `make build`).
+3. If feed directory or config references changed, run `make update` and verify resulting diffs.
+
+## Docs Authoring Rules
+
+### Code Snippets
+
+In docs content (`src/content/docs/**`) and docs-supporting components:
+
+- Do not use triple-backtick fenced code blocks.
+- Always render snippets with the `<Code>` component.
+- Use this import:
+  `import { Code } from '@astrojs/starlight/components';`
+- Do not use:
+  `import Code from "astro/components/Code.astro";`
+
+### Accuracy Rules
+
+- Prefer concrete, verifiable statements over aspirational wording.
+- Keep repo and path references explicit when guidance is cross-repo.
+- When referencing commands that belong to another repo, include that repo directory in the command example.
+
+## Commit and PR Expectations
+
+- Keep each commit scoped to one logical docs change.
+- Do not mix unrelated changes or unrelated generated diffs.
+- In PRs, call out:
+  - cross-repo assumptions
+  - generated files updated
+  - verification commands run

README.md

@@ -13,21 +13,24 @@ website.
 ### Quick Setup
 
 ```bash
-# Install dependencies and start development server
+# Install dependencies and refresh generated feed data
 make setup
+
+# Start the local Astro development server
+make dev
 ```
 
 ### 💻 Try in Browser
 
 You can develop html2rss directly in your browser using GitHub Codespaces:
 
-[Open in GitHub Codespaces](https://github.com/codespaces/new?repo=html2rss/html2rss)
+[Open in GitHub Codespaces](https://github.com/codespaces/new?repo=html2rss/html2rss.github.io)
 
 The Codespace provides a cloud development environment with Node.js and Ruby pre-installed. Run `make setup` to install dependencies and get started!
 
 ### Available Commands
 
-- `make setup` - Install dependencies and start dev server
+- `make setup` - Install dependencies and refresh generated feed data
 - `make dev` - Start Astro development server
 - `make build` - Build for production
 - `make preview` - Preview production build

src/components/docs/DockerComposeSnippet.astro

@@ -1,5 +1,5 @@
 ---
-import Code from "astro/components/Code.astro";
+import { Code } from "@astrojs/starlight/components";
 import { browserlessImage, caddyImage, watchtowerImage, webImage } from "../../data/docker";
 
 interface Props {

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

@@ -5,8 +5,7 @@ sidebar:
   order: 2
 ---
 
-import { Aside } from "@astrojs/starlight/components";
-import Code from "astro/components/Code.astro";
+import { Aside, Code } from "@astrojs/starlight/components";
 
 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.
 
@@ -70,11 +69,14 @@ This tells html2rss basic information about your feed - like giving it a name an
 
 **Example:**
 
-```yaml
-channel:
-  url: https://example.com/blog
-  title: My Awesome Blog
-```
+<Code
+  code={`
+  channel:
+    url: https://example.com/blog
+    title: My Awesome Blog
+  `}
+  lang="yaml"
+/>
 
 This says: "Look at this website and call the feed 'My Awesome Blog'"
 
@@ -84,16 +86,19 @@ This is where you tell the html2rss engine exactly what to find on the page. You
 
 **Example:**
 
-```yaml
-selectors:
-  items:
-    selector: "article.post"
-  title:
-    selector: "h2 a"
-  link:
-    selector: "h2 a"
-    attribute: href
-```
+<Code
+  code={`
+  selectors:
+    items:
+      selector: "article.post"
+    title:
+      selector: "h2 a"
+    link:
+      selector: "h2 a"
+      attribute: href
+  `}
+  lang="yaml"
+/>
 
 This says: "Find each article, get the title from the h2 anchor, and get the link from the same h2 anchor's href attribute"
 
@@ -107,20 +112,23 @@ This says: "Find each article, get the title from the h2 anchor, and get the lin
 
 **Step 2:** Create a file called `example.com.yml` with this basic structure:
 
-```yaml
-channel:
-  url: https://example.com/blog
-  title: My Blog
-
-selectors:
-  items:
-    selector: "article.post"
-  title:
-    selector: "h2 a"
-  link:
-    selector: "h2 a"
-    attribute: href
-```
+<Code
+  code={
+    "channel:\n" +
+    "  url: https://example.com/blog\n" +
+    "  title: My Blog\n" +
+    "\n" +
+    "selectors:\n" +
+    "  items:\n" +
+    '    selector: "article.post"\n' +
+    "  title:\n" +
+    '    selector: "h2 a"\n' +
+    "  link:\n" +
+    '    selector: "h2 a"\n' +
+    "    attribute: href"
+  }
+  lang="yaml"
+/>
 
 **Step 3:** Test it with your html2rss-web instance or the [Ruby gem](/ruby-gem/installation).
 
@@ -147,15 +155,11 @@ html2rss supports many configuration options:
 
 1. **Validate the config first:**
 
-   ```bash
-   html2rss validate your-config.yml
-   ```
+<Code code={`html2rss validate your-config.yml`} lang="bash" />
 
 2. **Then render the feed with the Ruby gem:**
 
-   ```bash
-   html2rss feed your-config.yml
-   ```
+<Code code={`html2rss feed your-config.yml`} lang="bash" />
 
 3. **Test with `html2rss-web`:** Add your config to the `feeds.yml` file and restart your instance
 
@@ -169,9 +173,11 @@ Some sites need a little more request budget than the defaults.
 - Use `--max-requests` when your config needs more than one request, for example pagination or other follow-up fetches.
 
 <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`}
+  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
+`}
   lang="bash"
 />
 

src/content/docs/get-involved/contributing.mdx

@@ -3,6 +3,8 @@ title: Contributing
 description: Learn how to contribute to the html2rss project
 ---
 
+import { Code } from "@astrojs/starlight/components";
+
 We're thrilled that you're interested in contributing to `html2rss`! There are many ways to get involved, and we welcome contributions of all kinds.
 
 ---
@@ -31,9 +33,7 @@ Are you missing an RSS feed for a website? You can create your own feed config a
 
 **Want to test your config first?** Use the [Ruby gem](/ruby-gem/installation) to test it locally:
 
-```bash
-html2rss feed your-config.yml
-```
+<Code code={`html2rss feed your-config.yml`} lang="bash" />
 
 ### 2. Host a Public Instance
 

src/content/docs/getting-started.mdx

@@ -5,7 +5,7 @@ sidebar:
   order: 1
 ---
 
-import Code from "astro/components/Code.astro";
+import { Code } from "@astrojs/starlight/components";
 
 This page points to the main onboarding flow.