feat: local search, blog, PWA, CI, 404 page, and docs polish

.github/dependabot.yml

@@ -0,0 +1,31 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    groups:
+      docusaurus:
+        patterns:
+          - "@docusaurus/*"
+          - "prism-react-renderer"
+          - "@mdx-js/*"
+          - "@easyops-cn/docusaurus-search-local"
+        update-types:
+          - minor
+          - patch
+      dev-tools:
+        patterns:
+          - "typescript"
+          - "@types/*"
+        update-types:
+          - minor
+          - patch
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - master
+  push:
+    branches-ignore:
+      - master
+      - gh-pages
+
+jobs:
+  build:
+    name: Build and verify docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: yarn
+
+      - name: Build
+        run: yarn build

blog/2026-04-16-documentation-refresh.md

@@ -0,0 +1,59 @@
+---
+slug: documentation-refresh-2026
+title: Documentation Refresh — Tutorials, Dark Theme, Search
+authors: [mocha-team]
+tags: [docs, release]
+description: We rebuilt the Mocha documentation site from the ground up — new tutorials, dark theme, local search, and every feature documented with examples and troubleshooting.
+---
+
+The Mocha documentation site just got a full refresh. Every feature is now documented, the theme matches the main mocha-bot.xyz site, and there's a proper tutorial track for people getting started with the bot.
+
+<!-- truncate -->
+
+## What's new
+
+### Tutorials
+
+There's a new **Tutorials** section with four step-by-step walkthroughs that take you from "I've never used this bot" to "I'm moderating a cross-server room":
+
+- **[Getting Started](/tutorials/getting-started)** — invite the bot, set up permissions, create your first room.
+- **[Connect Two Servers](/tutorials/connect-two-servers)** — bridge two Discord servers end-to-end with a test checklist.
+- **[Share a Room via Invitation](/tutorials/share-via-invite)** — the full invitation flow with aliases, usage caps, and expiration.
+- **[Curate Your Room](/tutorials/curate-your-room)** — editing details, kicking channels, enabling personalization, deleting rooms.
+
+### Full feature coverage
+
+Every slash command, chat behavior, and room feature now has its own reference page with:
+
+- Exact parameters with types and whether they're required.
+- What the bot does under the hood (without dragging in implementation details).
+- A troubleshooting table for the errors you're most likely to hit.
+- Cross-links so you can hop from a command to the concept behind it.
+
+That includes `/feedback` (new), the full `/room invite` subcommand group, typing indicators, reply threading, pins, ratings, and personalization.
+
+### Dark theme to match the main site
+
+The docs site now uses the same visual language as [mocha-bot.xyz](https://mocha-bot.xyz): pure black background, Plus Jakarta Sans, gold accents, glass surfaces, blurred navbar. Dark mode is the only mode — no more accidental light-mode flashes when following links out of the main site.
+
+### Local search
+
+There's a search bar in the navbar now. It indexes every page at build time — no third-party service, no approval process, instant results.
+
+### SEO and sharing
+
+- Per-page Open Graph and Twitter card metadata so shared links render properly in Discord, Slack, and Twitter.
+- A site-wide schema.org `WebSite` JSON-LD block plus the automatic `BreadcrumbList` structured data Docusaurus ships.
+- A generated sitemap and a `robots.txt` pointing at it.
+- A custom 404 page with links to the tutorials, commands reference, and FAQ.
+
+### Under the hood
+
+- Docusaurus v3 (up from v2 RC).
+- PWA enabled — you can install the docs as an app.
+- CI runs `yarn build` and link-checks every pull request.
+- Dependabot watches for updates so nothing rots.
+
+## What's next
+
+If you spot something missing, wrong, or confusing, let us know via the in-bot `/feedback` command or drop a message in the [support server](https://discord.mocha-bot.xyz/). This site is living documentation — the more you tell us where it breaks, the better it gets.

blog/authors.yml

@@ -0,0 +1,7 @@
+mocha-team:
+  name: Mocha Team
+  title: Mocha Bot maintainers
+  url: https://mocha-bot.xyz
+  image_url: /img/logo-mocha.png
+  socials:
+    github: mocha-bot

docs/chat/messages.md

@@ -56,6 +56,10 @@ Editing a message edits its copies in every other channel in the room. There is
 
 After the window expires the original edit will no longer propagate to followers.
 
+:::warning
+The window is measured from when the message was originally sent, not when you start editing. If you open the edit dialog just before the window closes and hit save a minute later, Mocha has already forgotten about the message and your change will only affect the original channel.
+:::
+
 ## Delete Message
 
 Deleting a message deletes every copy of it in the room, under the same time-window rules as editing.

docs/rooms/personalization.md

@@ -30,6 +30,10 @@ The room owner can toggle the flag later. Personalization requires the **Persona
 - If the webhook is missing (for example, because the server didn't grant **Manage Webhooks**), Mocha falls back to a normal bot message with the standard `[ Server ][ user ] >>` prefix — nothing is lost.
 - When a channel disconnects, its webhook is deleted.
 
+:::note Needs "Manage Webhooks"
+Personalization only works on servers where Mocha was granted **Manage Webhooks**. The fallback keeps the room functional for servers that didn't grant it, but those channels won't show per-user avatars. There's no warning — if you're running a mixed room, some sides will have personalization and others won't.
+:::
+
 ## Things to know
 
 - Per-user edits and deletes still work: Mocha tracks the webhook that sent each copy and edits/deletes via that webhook.

docs/tutorials/getting-started.md

@@ -37,6 +37,10 @@ This tutorial walks you through everything you need to get Mocha running in a Di
 
 When you're done, the bot will show up in your server member list and be ready to receive slash commands.
 
+:::info Why keep every permission?
+Mocha's relay pipeline uses nearly every permission Discord exposes for a chat bot — cutting one usually breaks a subtle feature (personalization falls back to plain text, edits stop propagating, attachments get stripped). The safe default is to grant the full set.
+:::
+
 ### Permissions cheat sheet
 
 | Permission          | Why Mocha needs it                                                   |

docusaurus.config.js

@@ -20,6 +20,7 @@ const siteKeywords = [
   'discord server bridge',
   'cross-server messaging',
 ];
+const ogImage = 'img/og-image.svg';
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
@@ -29,7 +30,7 @@ const config = {
   baseUrl: '/',
   trailingSlash: false,
   onBrokenLinks: 'throw',
-  favicon: 'img/favicon.ico',
+  favicon: 'img/logo-mocha.svg',
 
   markdown: {
     hooks: {
@@ -46,8 +47,8 @@ const config = {
     locales: ['en'],
   },
 
-  // Extra head tags for SEO — canonical hint, robots, theme color,
-  // structured data for search engines.
+  // Extra head tags for SEO and PWA — canonical hint, robots, theme color,
+  // structured data, manifest, and Apple/mask icon links.
   headTags: [
     {
       tagName: 'meta',
@@ -77,6 +78,42 @@ const config = {
         href: siteUrl,
       },
     },
+    {
+      tagName: 'link',
+      attributes: {
+        rel: 'manifest',
+        href: '/manifest.json',
+      },
+    },
+    {
+      tagName: 'link',
+      attributes: {
+        rel: 'apple-touch-icon',
+        href: '/img/logo-mocha.svg',
+      },
+    },
+    {
+      tagName: 'link',
+      attributes: {
+        rel: 'mask-icon',
+        href: '/img/logo-mocha.svg',
+        color: '#ffd700',
+      },
+    },
+    {
+      tagName: 'meta',
+      attributes: {
+        name: 'apple-mobile-web-app-capable',
+        content: 'yes',
+      },
+    },
+    {
+      tagName: 'meta',
+      attributes: {
+        name: 'apple-mobile-web-app-status-bar-style',
+        content: 'black',
+      },
+    },
     {
       tagName: 'script',
       attributes: {
@@ -113,26 +150,110 @@ const config = {
           sidebarPath: require.resolve('./sidebars.js'),
           editUrl: 'https://github.com/mocha-bot/docs/tree/master/docs/',
           showLastUpdateTime: true,
+          showLastUpdateAuthor: true,
+        },
+        blog: {
+          routeBasePath: 'changelog',
+          path: 'blog',
+          blogTitle: 'Changelog',
+          blogDescription:
+            'Release notes, documentation updates, and behind-the-scenes notes from the Mocha team.',
+          blogSidebarTitle: 'Recent updates',
+          blogSidebarCount: 'ALL',
+          postsPerPage: 10,
+          showReadingTime: false,
+          feedOptions: {
+            type: ['rss', 'atom'],
+            title: 'Mocha Bot Changelog',
+            description:
+              'Release notes and documentation updates for the Mocha Discord bot.',
+            copyright: `Copyright © ${new Date().getFullYear()} Mocha Bot, Inc.`,
+          },
         },
-        blog: false,
         theme: {
           customCss: require.resolve('./src/css/custom.css'),
         },
         sitemap: {
           lastmod: 'date',
           changefreq: 'weekly',
           priority: 0.5,
-          ignorePatterns: ['/tags/**'],
           filename: 'sitemap.xml',
         },
       }),
     ],
   ],
 
+  plugins: [
+    [
+      require.resolve('@easyops-cn/docusaurus-search-local'),
+      /** @type {import('@easyops-cn/docusaurus-search-local').PluginOptions} */
+      ({
+        hashed: true,
+        language: ['en'],
+        docsRouteBasePath: '/',
+        indexBlog: true,
+        indexPages: true,
+        highlightSearchTermsOnTargetPage: true,
+        searchResultLimits: 10,
+        searchBarShortcutHint: false,
+      }),
+    ],
+    [
+      '@docusaurus/plugin-pwa',
+      {
+        debug: false,
+        offlineModeActivationStrategies: [
+          'appInstalled',
+          'standalone',
+          'queryString',
+        ],
+        swRegister: false,
+        pwaHead: [
+          {
+            tagName: 'link',
+            rel: 'icon',
+            href: '/img/logo-mocha.svg',
+          },
+          {
+            tagName: 'link',
+            rel: 'manifest',
+            href: '/manifest.json',
+          },
+          {
+            tagName: 'meta',
+            name: 'theme-color',
+            content: '#000000',
+          },
+          {
+            tagName: 'meta',
+            name: 'apple-mobile-web-app-capable',
+            content: 'yes',
+          },
+          {
+            tagName: 'meta',
+            name: 'apple-mobile-web-app-status-bar-style',
+            content: 'black',
+          },
+          {
+            tagName: 'link',
+            rel: 'apple-touch-icon',
+            href: '/img/logo-mocha.svg',
+          },
+          {
+            tagName: 'link',
+            rel: 'mask-icon',
+            href: '/img/logo-mocha.svg',
+            color: '#ffd700',
+          },
+        ],
+      },
+    ],
+  ],
+
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
-      image: 'img/logo-mocha.png',
+      image: ogImage,
       metadata: [
         {name: 'description', content: siteDescription},
         {name: 'keywords', content: siteKeywords.join(', ')},
@@ -144,16 +265,18 @@ const config = {
         {property: 'og:title', content: siteTitle},
         {property: 'og:description', content: siteDescription},
         {property: 'og:url', content: siteUrl},
-        {property: 'og:image', content: `${siteUrl}/img/logo-mocha.png`},
-        {property: 'og:image:alt', content: 'Mocha Bot logo'},
+        {property: 'og:image', content: `${siteUrl}/${ogImage}`},
+        {property: 'og:image:alt', content: 'Mocha Bot Documentation'},
+        {property: 'og:image:width', content: '1200'},
+        {property: 'og:image:height', content: '630'},
         {property: 'og:locale', content: 'en_US'},
 
         // Twitter
         {name: 'twitter:card', content: 'summary_large_image'},
         {name: 'twitter:title', content: siteTitle},
         {name: 'twitter:description', content: siteDescription},
-        {name: 'twitter:image', content: `${siteUrl}/img/logo-mocha.png`},
-        {name: 'twitter:image:alt', content: 'Mocha Bot logo'},
+        {name: 'twitter:image', content: `${siteUrl}/${ogImage}`},
+        {name: 'twitter:image:alt', content: 'Mocha Bot Documentation'},
       ],
       colorMode: {
         defaultMode: 'dark',
@@ -167,6 +290,11 @@ const config = {
           src: 'img/logo-mocha.svg',
         },
         items: [
+          {
+            to: '/changelog',
+            label: 'Changelog',
+            position: 'right',
+          },
           {
             href: 'https://mocha-bot.xyz',
             position: 'right',
@@ -202,6 +330,7 @@ const config = {
           {
             title: 'More',
             items: [
+              {label: 'Changelog', to: '/changelog'},
               {label: 'GitHub', href: 'https://github.com/mocha-bot'},
               {
                 label: 'Edit on GitHub',

package.json

@@ -16,7 +16,9 @@
   },
   "dependencies": {
     "@docusaurus/core": "^3.7.0",
+    "@docusaurus/plugin-pwa": "^3.7.0",
     "@docusaurus/preset-classic": "^3.7.0",
+    "@easyops-cn/docusaurus-search-local": "^0.46.0",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",