Merge branch 'docs/tutorial' into 0.5-maintenance

Author: dahlia

AGENTS.md

@@ -700,3 +700,21 @@ mise run docs:dev      # Start development server
 
 Always run `mise run docs:build` before committing documentation changes to
 catch Twoslash type errors.
+
+
+Keeping tutorials in sync with their examples
+---------------------------------------------
+
+*docs/tutorial/rss-bot.md* and *examples/rss-bot/* are hand-synced: the
+tutorial's code samples are meant to be exact copies of the real, tested
+files, not paraphrased from memory.  A sample that merely reads plausibly
+can drift from the file it claims to show, missing a comment or a line,
+without failing any check, since `mise run docs:build` only type-checks
+a sample in isolation and has no idea what the real file looks like.
+Before treating a tutorial edit as done, diff every changed sample
+against the actual file, not just the parts that obviously changed.
+
+The same applies in the other direction: changing code under
+*examples/rss-bot/* without checking whether *docs/tutorial/rss-bot.md*
+needs a matching update is how that drift starts in the first place.
+When one changes, check the other.

deno.json

@@ -8,6 +8,7 @@
     "@fedify/vocab-runtime": "jsr:@fedify/vocab-runtime@~2.3.1",
     "@js-temporal/polyfill": "npm:@js-temporal/polyfill@^0.5.1",
     "@logtape/logtape": "jsr:@logtape/logtape@^2.2.3",
+    "@rowanmanning/feed-parser": "npm:@rowanmanning/feed-parser@^2.1.3",
     "@std/fs": "jsr:@std/fs@^1.0.24",
     "@std/path": "jsr:@std/path@^1.1.6",
     "hono": "jsr:@hono/hono@^4.12.27",

deno.lock

@@ -31,6 +31,17 @@ if (process.env.PLAUSIBLE_DOMAIN) {
   ];
 }
 
+const learn = {
+  text: "Learn",
+  items: [
+    { text: "What is BotKit?", link: "/intro.md" },
+    { text: "Getting started", link: "/start.md" },
+    { text: "Building an RSS bot", link: "/tutorial/rss-bot.md" },
+    { text: "Recipes", link: "/recipes.md" },
+    { text: "Examples", link: "/examples.md" },
+  ],
+};
+
 const concepts = {
   text: "Concepts",
   items: [
@@ -83,18 +94,16 @@ export default defineConfig({
     logo: "/logo.svg",
     nav: [
       { text: "Home", link: "/" },
-      { text: "About", link: "/intro.md" },
-      { text: "Start", link: "/start.md" },
+      learn,
       concepts,
       deploy,
       references,
-      { text: "Recipes", link: "/recipes.md" },
-      { text: "Examples", link: "/examples.md" },
     ],
 
     sidebar: [
       { text: "What is BotKit?", link: "/intro.md" },
       { text: "Getting started", link: "/start.md" },
+      { text: "Building an RSS bot", link: "/tutorial/rss-bot.md" },
       concepts,
       deploy,
       references,

docs/.vitepress/config.mts

@@ -153,6 +153,33 @@ multiple bot groups are probed in the order they were created.
 <!-- hongdown-enable -->
 
 
+RSS/Atom feed bot
+-----------------
+
+The following example shows a bot that polls an RSS, Atom, or RDF feed on
+an interval and publishes new entries to the fediverse, replies to
+mentions with its status, and persists both its own state and BotKit's
+data across restarts using SQLite.  It's covered in depth, file by file,
+in the [*Building an RSS bot*](./tutorial/rss-bot.md) tutorial, which also
+grows it into a `createInstance()`-based instance hosting one bot per
+feed, registered by mentioning the instance with a feed's URL, and ends
+with a self-hosted deployment.
+
+<!-- hongdown-disable -->
+
+::: code-group
+
+<<< @/../examples/rss-bot/feed.ts [feed.ts]
+
+<<< @/../examples/rss-bot/db.ts [db.ts]
+
+<<< @/../examples/rss-bot/instance.ts [instance.ts]
+
+:::
+
+<!-- hongdown-enable -->
+
+
 FediChatBot
 -----------
 

docs/examples.md

@@ -12,6 +12,7 @@
     "@fedify/vocab": "^2.3.1",
     "@fedify/vocab-runtime": "^2.3.1",
     "@js-temporal/polyfill": "catalog:",
+    "@rowanmanning/feed-parser": "^2.1.3",
     "@shikijs/vitepress-twoslash": "^4.3.1",
     "@types/deno": "^2.3.0",
     "@types/node": "^24.0.3",