Skip to content

Commit b0c14be

Browse files
Aldiwildan77Aldiwildan77
authored
feat: local search, blog, PWA, CI, 404 page, and docs polish (#3)
* feat: local search, blog, PWA, CI, 404 page, and docs polish Local search: - Add @easyops-cn/docusaurus-search-local with hashed index, keyed to the docs routeBasePath (/) so the search bar covers every page. Blog / Changelog: - Re-enable the blog preset as /changelog with RSS + Atom feeds. - Ship one starter post announcing the docs refresh. - Add "Changelog" link to the navbar. PWA: - Add @docusaurus/plugin-pwa with manifest.json, apple-touch-icon, and mask-icon. swRegister is off for now to avoid cache surprises. CI: - New ci.yml that runs yarn build on every PR — catches MDX errors and broken internal links before merge. - New dependabot.yml to keep Docusaurus, Actions, and dev deps current. Custom 404: - Branded 404 page with three "go somewhere useful" tiles (Intro, Getting Started, Commands) and links to the FAQ and support server. Open Graph image: - New 1200×630 SVG at static/img/og-image.svg matching the land theme. OG and Twitter card metadata now point at it. Favicon: - Switch from the default Docusaurus favicon.ico to img/logo-mocha.svg. Other polish: - showLastUpdateAuthor enabled in docs preset. - Copy-button CSS: visible border, gold hover accent, "copied" state. - Admonitions on three pages: permissions info box in Getting Started, edit-window warning in Messages, Manage Webhooks note in Personalization. * fix(ci): use bare yarn install for yarn v1 compatibility yarn v1 doesn't accept --frozen-lockfile=false (it's not a valid flag format). And since no lockfile is committed (.gitignore excludes *.lock), the frozen-lockfile check would fail anyway. Match the existing gh-pages.yml pattern: plain yarn.
1 parent cabc161 commit b0c14be

14 files changed

Lines changed: 529 additions & 10 deletions

File tree

‎.github/dependabot.yml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
version: 2
2+
updates:
3+
- package-ecosystem: npm
4+
directory: /
5+
schedule:
6+
interval: weekly
7+
day: monday
8+
open-pull-requests-limit: 5
9+
groups:
10+
docusaurus:
11+
patterns:
12+
- "@docusaurus/*"
13+
- "prism-react-renderer"
14+
- "@mdx-js/*"
15+
- "@easyops-cn/docusaurus-search-local"
16+
update-types:
17+
- minor
18+
- patch
19+
dev-tools:
20+
patterns:
21+
- "typescript"
22+
- "@types/*"
23+
update-types:
24+
- minor
25+
- patch
26+
27+
- package-ecosystem: github-actions
28+
directory: /
29+
schedule:
30+
interval: weekly
31+
day: monday

‎.github/workflows/ci.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- master
7+
push:
8+
branches-ignore:
9+
- master
10+
- gh-pages
11+
12+
jobs:
13+
build:
14+
name: Build and verify docs
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Setup Node
20+
uses: actions/setup-node@v4
21+
with:
22+
node-version: '20'
23+
24+
- name: Install dependencies
25+
run: yarn
26+
27+
- name: Build
28+
run: yarn build

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

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
slug: documentation-refresh-2026
3+
title: Documentation Refresh — Tutorials, Dark Theme, Search
4+
authors: [mocha-team]
5+
tags: [docs, release]
6+
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.
7+
---
8+
9+
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.
10+
11+
<!-- truncate -->
12+
13+
## What's new
14+
15+
### Tutorials
16+
17+
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":
18+
19+
- **[Getting Started](/tutorials/getting-started)** — invite the bot, set up permissions, create your first room.
20+
- **[Connect Two Servers](/tutorials/connect-two-servers)** — bridge two Discord servers end-to-end with a test checklist.
21+
- **[Share a Room via Invitation](/tutorials/share-via-invite)** — the full invitation flow with aliases, usage caps, and expiration.
22+
- **[Curate Your Room](/tutorials/curate-your-room)** — editing details, kicking channels, enabling personalization, deleting rooms.
23+
24+
### Full feature coverage
25+
26+
Every slash command, chat behavior, and room feature now has its own reference page with:
27+
28+
- Exact parameters with types and whether they're required.
29+
- What the bot does under the hood (without dragging in implementation details).
30+
- A troubleshooting table for the errors you're most likely to hit.
31+
- Cross-links so you can hop from a command to the concept behind it.
32+
33+
That includes `/feedback` (new), the full `/room invite` subcommand group, typing indicators, reply threading, pins, ratings, and personalization.
34+
35+
### Dark theme to match the main site
36+
37+
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.
38+
39+
### Local search
40+
41+
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.
42+
43+
### SEO and sharing
44+
45+
- Per-page Open Graph and Twitter card metadata so shared links render properly in Discord, Slack, and Twitter.
46+
- A site-wide schema.org `WebSite` JSON-LD block plus the automatic `BreadcrumbList` structured data Docusaurus ships.
47+
- A generated sitemap and a `robots.txt` pointing at it.
48+
- A custom 404 page with links to the tutorials, commands reference, and FAQ.
49+
50+
### Under the hood
51+
52+
- Docusaurus v3 (up from v2 RC).
53+
- PWA enabled — you can install the docs as an app.
54+
- CI runs `yarn build` and link-checks every pull request.
55+
- Dependabot watches for updates so nothing rots.
56+
57+
## What's next
58+
59+
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‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
mocha-team:
2+
name: Mocha Team
3+
title: Mocha Bot maintainers
4+
url: https://mocha-bot.xyz
5+
image_url: /img/logo-mocha.png
6+
socials:
7+
github: mocha-bot

‎docs/chat/messages.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,10 @@ Editing a message edits its copies in every other channel in the room. There is
5656

5757
After the window expires the original edit will no longer propagate to followers.
5858

59+
:::warning
60+
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.
61+
:::
62+
5963
## Delete Message
6064

6165
Deleting a message deletes every copy of it in the room, under the same time-window rules as editing.

‎docs/rooms/personalization.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,10 @@ The room owner can toggle the flag later. Personalization requires the **Persona
3030
- 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.
3131
- When a channel disconnects, its webhook is deleted.
3232

33+
:::note Needs "Manage Webhooks"
34+
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.
35+
:::
36+
3337
## Things to know
3438

3539
- 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‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,10 @@ This tutorial walks you through everything you need to get Mocha running in a Di
3737

3838
When you're done, the bot will show up in your server member list and be ready to receive slash commands.
3939

40+
:::info Why keep every permission?
41+
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.
42+
:::
43+
4044
### Permissions cheat sheet
4145

4246
| Permission | Why Mocha needs it |

‎docusaurus.config.js‎

Lines changed: 139 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ const siteKeywords = [
2020
'discord server bridge',
2121
'cross-server messaging',
2222
];
23+
const ogImage = 'img/og-image.svg';
2324

2425
/** @type {import('@docusaurus/types').Config} */
2526
const config = {
@@ -29,7 +30,7 @@ const config = {
2930
baseUrl: '/',
3031
trailingSlash: false,
3132
onBrokenLinks: 'throw',
32-
favicon: 'img/favicon.ico',
33+
favicon: 'img/logo-mocha.svg',
3334

3435
markdown: {
3536
hooks: {
@@ -46,8 +47,8 @@ const config = {
4647
locales: ['en'],
4748
},
4849

49-
// Extra head tags for SEO — canonical hint, robots, theme color,
50-
// structured data for search engines.
50+
// Extra head tags for SEO and PWA — canonical hint, robots, theme color,
51+
// structured data, manifest, and Apple/mask icon links.
5152
headTags: [
5253
{
5354
tagName: 'meta',
@@ -77,6 +78,42 @@ const config = {
7778
href: siteUrl,
7879
},
7980
},
81+
{
82+
tagName: 'link',
83+
attributes: {
84+
rel: 'manifest',
85+
href: '/manifest.json',
86+
},
87+
},
88+
{
89+
tagName: 'link',
90+
attributes: {
91+
rel: 'apple-touch-icon',
92+
href: '/img/logo-mocha.svg',
93+
},
94+
},
95+
{
96+
tagName: 'link',
97+
attributes: {
98+
rel: 'mask-icon',
99+
href: '/img/logo-mocha.svg',
100+
color: '#ffd700',
101+
},
102+
},
103+
{
104+
tagName: 'meta',
105+
attributes: {
106+
name: 'apple-mobile-web-app-capable',
107+
content: 'yes',
108+
},
109+
},
110+
{
111+
tagName: 'meta',
112+
attributes: {
113+
name: 'apple-mobile-web-app-status-bar-style',
114+
content: 'black',
115+
},
116+
},
80117
{
81118
tagName: 'script',
82119
attributes: {
@@ -113,26 +150,110 @@ const config = {
113150
sidebarPath: require.resolve('./sidebars.js'),
114151
editUrl: 'https://github.com/mocha-bot/docs/tree/master/docs/',
115152
showLastUpdateTime: true,
153+
showLastUpdateAuthor: true,
154+
},
155+
blog: {
156+
routeBasePath: 'changelog',
157+
path: 'blog',
158+
blogTitle: 'Changelog',
159+
blogDescription:
160+
'Release notes, documentation updates, and behind-the-scenes notes from the Mocha team.',
161+
blogSidebarTitle: 'Recent updates',
162+
blogSidebarCount: 'ALL',
163+
postsPerPage: 10,
164+
showReadingTime: false,
165+
feedOptions: {
166+
type: ['rss', 'atom'],
167+
title: 'Mocha Bot Changelog',
168+
description:
169+
'Release notes and documentation updates for the Mocha Discord bot.',
170+
copyright: `Copyright © ${new Date().getFullYear()} Mocha Bot, Inc.`,
171+
},
116172
},
117-
blog: false,
118173
theme: {
119174
customCss: require.resolve('./src/css/custom.css'),
120175
},
121176
sitemap: {
122177
lastmod: 'date',
123178
changefreq: 'weekly',
124179
priority: 0.5,
125-
ignorePatterns: ['/tags/**'],
126180
filename: 'sitemap.xml',
127181
},
128182
}),
129183
],
130184
],
131185

186+
plugins: [
187+
[
188+
require.resolve('@easyops-cn/docusaurus-search-local'),
189+
/** @type {import('@easyops-cn/docusaurus-search-local').PluginOptions} */
190+
({
191+
hashed: true,
192+
language: ['en'],
193+
docsRouteBasePath: '/',
194+
indexBlog: true,
195+
indexPages: true,
196+
highlightSearchTermsOnTargetPage: true,
197+
searchResultLimits: 10,
198+
searchBarShortcutHint: false,
199+
}),
200+
],
201+
[
202+
'@docusaurus/plugin-pwa',
203+
{
204+
debug: false,
205+
offlineModeActivationStrategies: [
206+
'appInstalled',
207+
'standalone',
208+
'queryString',
209+
],
210+
swRegister: false,
211+
pwaHead: [
212+
{
213+
tagName: 'link',
214+
rel: 'icon',
215+
href: '/img/logo-mocha.svg',
216+
},
217+
{
218+
tagName: 'link',
219+
rel: 'manifest',
220+
href: '/manifest.json',
221+
},
222+
{
223+
tagName: 'meta',
224+
name: 'theme-color',
225+
content: '#000000',
226+
},
227+
{
228+
tagName: 'meta',
229+
name: 'apple-mobile-web-app-capable',
230+
content: 'yes',
231+
},
232+
{
233+
tagName: 'meta',
234+
name: 'apple-mobile-web-app-status-bar-style',
235+
content: 'black',
236+
},
237+
{
238+
tagName: 'link',
239+
rel: 'apple-touch-icon',
240+
href: '/img/logo-mocha.svg',
241+
},
242+
{
243+
tagName: 'link',
244+
rel: 'mask-icon',
245+
href: '/img/logo-mocha.svg',
246+
color: '#ffd700',
247+
},
248+
],
249+
},
250+
],
251+
],
252+
132253
themeConfig:
133254
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
134255
({
135-
image: 'img/logo-mocha.png',
256+
image: ogImage,
136257
metadata: [
137258
{name: 'description', content: siteDescription},
138259
{name: 'keywords', content: siteKeywords.join(', ')},
@@ -144,16 +265,18 @@ const config = {
144265
{property: 'og:title', content: siteTitle},
145266
{property: 'og:description', content: siteDescription},
146267
{property: 'og:url', content: siteUrl},
147-
{property: 'og:image', content: `${siteUrl}/img/logo-mocha.png`},
148-
{property: 'og:image:alt', content: 'Mocha Bot logo'},
268+
{property: 'og:image', content: `${siteUrl}/${ogImage}`},
269+
{property: 'og:image:alt', content: 'Mocha Bot Documentation'},
270+
{property: 'og:image:width', content: '1200'},
271+
{property: 'og:image:height', content: '630'},
149272
{property: 'og:locale', content: 'en_US'},
150273

151274
// Twitter
152275
{name: 'twitter:card', content: 'summary_large_image'},
153276
{name: 'twitter:title', content: siteTitle},
154277
{name: 'twitter:description', content: siteDescription},
155-
{name: 'twitter:image', content: `${siteUrl}/img/logo-mocha.png`},
156-
{name: 'twitter:image:alt', content: 'Mocha Bot logo'},
278+
{name: 'twitter:image', content: `${siteUrl}/${ogImage}`},
279+
{name: 'twitter:image:alt', content: 'Mocha Bot Documentation'},
157280
],
158281
colorMode: {
159282
defaultMode: 'dark',
@@ -167,6 +290,11 @@ const config = {
167290
src: 'img/logo-mocha.svg',
168291
},
169292
items: [
293+
{
294+
to: '/changelog',
295+
label: 'Changelog',
296+
position: 'right',
297+
},
170298
{
171299
href: 'https://mocha-bot.xyz',
172300
position: 'right',
@@ -202,6 +330,7 @@ const config = {
202330
{
203331
title: 'More',
204332
items: [
333+
{label: 'Changelog', to: '/changelog'},
205334
{label: 'GitHub', href: 'https://github.com/mocha-bot'},
206335
{
207336
label: 'Edit on GitHub',

‎package.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,9 @@
1616
},
1717
"dependencies": {
1818
"@docusaurus/core": "^3.7.0",
19+
"@docusaurus/plugin-pwa": "^3.7.0",
1920
"@docusaurus/preset-classic": "^3.7.0",
21+
"@easyops-cn/docusaurus-search-local": "^0.46.0",
2022
"@mdx-js/react": "^3.0.0",
2123
"clsx": "^2.0.0",
2224
"prism-react-renderer": "^2.3.0",

0 commit comments

Comments
 (0)