Skip to content

Commit 8100a6d

Browse files
Aldiwildan77Aldiwildan77
committed
feat: upgrade to Docusaurus v3, adopt land dark theme, add tutorials
- Bump @docusaurus/* to ^3.7, React to 18, prism-react-renderer to v2, MDX to v3. Pin webpack to ~5.100 to avoid the ProgressPlugin schema regression in 5.101+. Migrate onBrokenMarkdownLinks to markdown.hooks.onBrokenMarkdownLinks. - Port the mocha-bot.xyz dark theme into custom.css: black background, Plus Jakarta Sans, gold accents, glass surfaces, blurred navbar, and force dark-only with no toggle. - Add a Tutorials section with four step-by-step walkthroughs: Getting Started, Connect Two Servers, Share via Invitation, and Curate Your Room. Shift existing categories to make room. - Expand Help, Feedback, Replies & Pins, Typing, and Ratings pages with full behavior, troubleshooting tables, and cross-links so every feature is documented end-to-end.
1 parent f800e86 commit 8100a6d

20 files changed

Lines changed: 999 additions & 74 deletions

‎docs/chat/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"label": "Chat",
3-
"position": 3,
3+
"position": 4,
44
"link": {
55
"type": "generated-index"
66
}

‎docs/chat/reactions-replies.md‎

Lines changed: 56 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,64 @@ sidebar_position: 2
44

55
# Replies & Pins
66

7+
Beyond broadcasting the raw content of a message, Mocha preserves two Discord affordances across the bridge: **reply threading** and **pins**. This page describes how they behave and where the edges are.
8+
79
## Reply threading
810

9-
Replying to a message in one channel is mirrored as a reply in every other channel in the room, pointing at the corresponding copy of the original message. Mocha keeps a per-message map of follower messages so the correct reply target is used on each side.
11+
### What happens
12+
13+
When you reply to a message in a connected channel:
14+
15+
1. Mocha looks up the message you're replying to in its reply-to cache.
16+
2. For each other channel in the room, it finds the **corresponding copy** of that message (not the one you clicked on — the one that was delivered to that channel).
17+
3. It sends your reply as a native Discord reply pointing at that copy.
18+
19+
The result: every server in the room sees the reply threaded to the right message, not just a floating comment.
20+
21+
### What it relies on
22+
23+
- The original message must still be in the **reply-to cache**. Mocha keeps it for as long as the room's **Max message TTL** allows — see the [edit/delete window table](/chat/messages#edit-message) for the current values.
24+
- If the original message has fallen out of cache, the reply is delivered as a plain message (no threading).
25+
- Reply threading works the same way with and without [personalization](/rooms/personalization).
26+
27+
### Try it
28+
29+
1. Send a message in channel A of a room.
30+
2. In channel B, click **Reply** on the copy that arrived there.
31+
3. Send your reply — you should see it threaded to the original on **both** sides.
32+
33+
## Pins
34+
35+
### What happens
36+
37+
When you pin a message in any connected channel, Mocha pins every follower copy of it in the other channels in the room. Unpin actions are **not** mirrored — if you remove a pin on one side, the other side's pin stays.
38+
39+
### What it relies on
40+
41+
- The follower copies must still be tracked. If the room's message TTL has elapsed, Mocha no longer knows which messages to pin and the pin stays local to the channel you acted in.
42+
- Mocha needs **Manage Messages** in every channel it's pinning into. If the permission is missing in one server, that side silently fails to pin — the bot logs it but the user doesn't see an error.
43+
- Discord limits every channel to 50 pins. If a channel is already at the limit, the new pin won't go through.
44+
45+
### Try it
46+
47+
1. Pin any recent relayed message on one side.
48+
2. Check the pinned messages list on the other side — the same message should be there.
49+
50+
## Not yet mirrored
51+
52+
For transparency, a few things Discord supports that Mocha **does not** propagate:
53+
54+
- **Reactions** — adding or removing an emoji reaction only affects the local message.
55+
- **Threads (Discord's native threads)** — Mocha relays into the parent channel only.
56+
- **Forum posts** — Mocha relays the post content but doesn't mirror tags or the thread structure.
57+
- **Unpin** — one-way pin only.
1058

11-
Reply threading only works while the original message is still cached — see the edit/delete window table on [Messages](/chat/messages). Once the cache expires, the reply becomes a normal message.
59+
If you need any of these, file a [feedback](/commands/feedback) request — we track demand that way.
1260

13-
## Pinning
61+
## Troubleshooting
1462

15-
If you pin a message, the bot pins every follower copy of that message in the other channels in the room. Unpin actions are not mirrored.
63+
| Symptom | Likely cause |
64+
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
65+
| My reply comes through as a normal message | The original message has aged past the room's **Max message TTL**. |
66+
| Pin works on one side, fails on another | Missing **Manage Messages** permission on the failing side, or that channel has already hit 50 pins. |
67+
| I unpinned but the pin persists elsewhere | Expected — unpin is not mirrored. |

‎docs/chat/typing.md‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,39 @@ sidebar_position: 3
44

55
# Typing Indicators
66

7-
When you start typing in a connected channel, Mocha forwards the typing indicator to every other channel in the same room. The sender's own channel and the bot's own typing events are excluded to prevent loops. There is no configuration — the indicator is sent for as long as Discord reports you as typing.
7+
One of the little touches that makes Mocha rooms feel like a single conversation: when you start typing, the other channels in the room see "Mocha Bot is typing..." too. This page explains exactly how it works and where its limits are.
8+
9+
## What happens
10+
11+
1. Discord tells Mocha that a user started typing in a connected channel.
12+
2. Mocha confirms the channel is in a room and fetches the list of sibling channels.
13+
3. For each sibling (excluding the one you're typing in), it calls Discord's **Trigger Typing Indicator** API.
14+
4. Discord's standard 10-second typing TTL takes over — the indicator clears itself after that.
15+
16+
There's no configuration. It's always on for every connected channel.
17+
18+
## What you'll see
19+
20+
- **Indicator name** — always "Mocha Bot" (Discord attributes triggered typing to the bot, not the original user).
21+
- **Duration** — follows Discord's default: ~10 seconds, or until Mocha sends a real message, whichever comes first.
22+
- **Cross-server** — same behavior no matter how many channels are in the room.
23+
24+
## What's excluded
25+
26+
To keep the typing event clean and prevent loops:
27+
28+
- **Your own channel** never echoes the indicator back to itself.
29+
- **The bot's own typing** events are ignored (a previous version of the relay did forward them, which caused a typing feedback loop).
30+
- Channels that aren't in any room produce no typing events.
31+
32+
## Why is the avatar always the bot?
33+
34+
Typing indicators in Discord are authored by whoever calls the `Trigger Typing Indicator` endpoint. Since that's Mocha on the receiving side, the receiving channel sees "Mocha Bot is typing..." rather than the real user. There is no API to impersonate a different user for typing indicators, even with [personalization](/rooms/personalization) turned on (personalization applies to message authorship, not typing events).
35+
36+
## Troubleshooting
37+
38+
| Symptom | Likely cause |
39+
| -------------------------------------------------------- | --------------------------------------------------------------------- |
40+
| Typing indicator doesn't show up on the other channel | The channels aren't actually in the same room. Run `/room info` to double-check. |
41+
| Indicator appears but message never arrives | You started typing but never pressed enter, **or** the send failed due to permissions. Check Mocha's **Send Messages** permission. |
42+
| Indicator lingers after the user stops | Discord's 10-second TTL is still running. It'll clear itself. |

‎docs/commands/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"label": "Commands",
3-
"position": 2,
3+
"position": 3,
44
"link": {
55
"type": "generated-index"
66
}

‎docs/commands/feedback.md‎

Lines changed: 40 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ sidebar_position: 3
44

55
# Feedback
66

7-
Send feedback directly to the bot developers. Opens a modal form; your submission is forwarded to the developer channel together with the server and user it came from.
7+
Send feedback to the Mocha maintainers directly from Discord. The command opens a modal form that ends up as a formatted message in the developer channel, tagged with the server and user it came from so we can follow up if needed.
88

99
## Slash Commands
1010

@@ -13,14 +13,46 @@ Send feedback directly to the bot developers. Opens a modal form; your submissio
1313
**Usage**
1414

1515
```md
16-
feedback
16+
/feedback
1717
```
1818

19-
**Modal fields**
19+
**What happens next**
2020

21-
| Field | Required | Notes |
22-
| ---------- | -------- | ------------------------------------------------------------------ |
23-
| `Type` | yes | One of `bug`, `suggestion`, `feature_request`, or `other`. |
24-
| `Feedback` | yes | Free-form description, up to 2000 characters. |
21+
1. Mocha responds with an ephemeral modal titled **Send Feedback**.
22+
2. You fill in two fields.
23+
3. You submit — Mocha replies *"Thank you for your feedback!"* and forwards the details to the developer channel.
2524

26-
If none of the known types are entered, the submission is still accepted and categorised as `other`.
25+
## Modal fields
26+
27+
| Field | Required | Limits | Description |
28+
| ---------- | -------- | -------------------- | ------------------------------------------------------------- |
29+
| **Type** | yes | 3–20 characters | One of `bug`, `suggestion`, `feature_request`, `other`. |
30+
| **Feedback** | yes | up to 2000 characters | Free-form description. Be specific — the more context, the better. |
31+
32+
If you type something that isn't one of the four known values for **Type**, Mocha will accept the submission and quietly categorise it as `other`. You don't need to worry about spelling it exactly.
33+
34+
## What the maintainers see
35+
36+
Your submission is posted to the developer channel as an embed containing:
37+
38+
- **Title** — "Received a feedback!"
39+
- **Description** — the body you typed.
40+
- **Color** — tinted by feedback type (bug, suggestion, feature_request, other each have their own color).
41+
- **Author** — your Discord tag and avatar.
42+
- **Type field** — the category.
43+
- **Guild field** — the server name and ID the feedback came from.
44+
- **User field** — your display name and user ID.
45+
- **Timestamp** — when you submitted.
46+
47+
## Writing effective feedback
48+
49+
To help us act on your report quickly:
50+
51+
- **Bugs** — include the command or action you ran, what you expected, what happened, and (if possible) the room ID.
52+
- **Suggestions / feature requests** — describe the problem you're trying to solve, not just the solution you have in mind. We can usually find a better fit for the underlying need.
53+
- **Other** — use this for questions, praise, or anything that doesn't fit the first three. We read all of it.
54+
55+
## See also
56+
57+
- [Support server](https://discord.mocha-bot.xyz/) — real-time help from the community.
58+
- [Frequent Searches](/others/frequent-searches) — answers to the most common questions before you reach for `/feedback`.

‎docs/commands/help.md‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,35 @@ sidebar_position: 1
44

55
# Help
66

7-
Help commands is a command line tool for bot information.
7+
The help command is the lowest-friction way to check whether Mocha is alive in a server and remember what commands it ships.
88

99
## Slash Commands
1010

1111
### Help
1212

13-
This command is used to get the list of available commands. The bot replies with an embed that links to the [Mocha website](https://mocha-bot.xyz).
13+
Run this in any channel where the bot is present. It replies with an ephemeral embed listing the available commands and links to the [Mocha website](https://mocha-bot.xyz).
1414

1515
**Usage**
1616

1717
```md
18-
help
18+
/help
1919
```
20+
21+
**What you'll see**
22+
23+
- An embed with the bot's name and avatar.
24+
- A short description of what Mocha does.
25+
- A direct link to [mocha-bot.xyz](https://mocha-bot.xyz) if you need the bot's public face.
26+
27+
The response is **ephemeral** — only you see it. Nobody else in the channel is pinged or cluttered.
28+
29+
## When to use it
30+
31+
- **First run** — to confirm slash commands are registered. If `/help` isn't in the autocomplete list, Discord hasn't finished syncing commands yet — give it a minute and reload with `Ctrl`/`Cmd` + `R`.
32+
- **Quick reference** — when you can't remember the exact name of a subcommand like `/room invite join`.
33+
- **Verifying the bot** — if the bot seems unresponsive, `/help` is the cheapest ping to check that it's still listening.
34+
35+
## See also
36+
37+
- [Commands overview](/category/commands) — every slash command Mocha understands.
38+
- [Getting Started](/tutorials/getting-started) — the full onboarding walkthrough.

‎docs/index.mdx‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,17 +10,26 @@ Let's discover **Mocha in less than 5 minutes**.
1010

1111
Mocha is a Discord bot that links channels across different servers into **rooms**. Anything posted in one channel is broadcast to every other channel in the room — including edits, deletes, replies, pins, attachments, stickers, and typing indicators. See [Rooms Overview](/rooms/overview) for the concept.
1212

13-
## Getting Started
13+
## New here? Start with the tutorials.
1414

15-
Invite the bot to your server from **[mocha-bot.xyz](https://mocha-bot.xyz)**, then in any channel run:
15+
If this is your first time with Mocha, skip the reference docs and follow the step-by-step walkthroughs in order:
16+
17+
1. [Getting Started](/tutorials/getting-started) — invite the bot, create your first room, run a basic check.
18+
2. [Connect two servers](/tutorials/connect-two-servers) — bridge two Discord servers end-to-end.
19+
3. [Share a room via invitation](/tutorials/share-via-invite) — create codes so people can join without sharing IDs.
20+
4. [Curate your room](/tutorials/curate-your-room) — edit details, kick channels, manage rooms.
21+
22+
## Quick start
23+
24+
If you already know your way around Discord bots, the 30-second version is:
1625

1726
```md
18-
room create
27+
/room create
1928
```
2029

21-
That channel is now the owner of a new room. Share the resulting room ID (or an [invitation code](/rooms/invitations)) with friends so their channels can `room join`.
30+
That channel is now the owner of a new room. Share its ID (or an [invitation code](/rooms/invitations)) and other channels can `/room join` it.
2231

23-
### Learn more
32+
## Reference
2433

2534
- [Commands](/category/commands) — every slash command Mocha understands.
2635
- [Chat](/category/chat) — how messages, edits, replies, pins, mentions, and `!tmp` work.
@@ -33,4 +42,4 @@ If you're having issues with the bot, check the [Frequent Searches](/others/freq
3342

3443
## Making suggestions
3544

36-
Use the [`feedback`](/commands/feedback) slash command from any server the bot is in, or drop a message in the [support server](https://discord.mocha-bot.xyz/).
45+
Use the [`/feedback`](/commands/feedback) slash command from any server the bot is in, or drop a message in the [support server](https://discord.mocha-bot.xyz/).

‎docs/others/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "Others",
3-
"position": 6
3+
"position": 7
44
}

‎docs/rooms/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"label": "Rooms",
3-
"position": 4,
3+
"position": 5,
44
"link": {
55
"type": "generated-index"
66
}

‎docs/rooms/ratings.md‎

Lines changed: 35 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,44 @@ sidebar_position: 4
44

55
# Ratings
66

7-
Every room can be rated 1–5 stars by any member of a connected channel. The aggregate rating is shown in [`room info`](/commands/room#info) and on the [public room page](/web/room-page).
7+
Rooms can be rated 1 to 5 stars by any user who's in a connected channel. Ratings are the signal we surface on the [public room directory](/web/discover) and on each room's `/room info` embed, so healthy, useful rooms float to the top.
88

99
## Leaving a rating
1010

11-
1. Run `room info` in a channel that is connected to the room.
12-
2. Click **Rate this room**.
13-
3. Pick a star count from the dropdown.
11+
1. In any channel that's connected to the room, run:
12+
```md
13+
/room info
14+
```
15+
2. At the bottom of the embed, click **Rate this room** (secondary button).
16+
3. A dropdown with 1–5 stars appears.
17+
4. Pick a value. Mocha replies with *"You have rated **the room** with N stars"*.
1418

15-
If you have already rated the room, the dropdown message tells you your current score. Selecting a new value updates it — each user has exactly one rating per room.
19+
The vote updates the room's average immediately.
1620

17-
## Aggregation
21+
## One rating per user per room
1822

19-
The rating shown on `room info` (field **Rate**) and on the web room page is the average of all users' ratings. Rating changes update the average immediately.
23+
Each user has exactly one rating per room. If you click **Rate this room** again after already rating:
24+
25+
- The prompt changes to *"Looks like you've already rated this room with N stars. Feel free to update your rating if you'd like to make a change!"*
26+
- Picking a new star value **overwrites** your previous rating.
27+
28+
There's no way to "un-rate" — picking 1 star is as low as it goes.
29+
30+
## Where ratings show up
31+
32+
- **`/room info`** — the **Rate** field in the embed shows the running average as a two-decimal number (e.g. `4.25`). A brand-new room with zero ratings shows `0.00`.
33+
- **Public room directory** — [Discover Rooms](/web/discover) shows the average rating on every room card and lets you filter the list by rating.
34+
- **Room page** — the [web room page](/web/room-page) surfaces the rating prominently next to the room title.
35+
36+
## How the average is calculated
37+
38+
It's a plain arithmetic mean — the sum of every active user's rating divided by how many users have rated. Changing your own rating updates the average in real time; there's no rolling window or decay.
39+
40+
## Who can rate
41+
42+
Anyone whose channel is connected to the room. You don't need to be the server owner, the channel owner, or the room owner. You just need to be present in a channel that's part of the room when you run `/room info`.
43+
44+
## See also
45+
46+
- [Rooms overview](/rooms/overview) — what a room is and how it's structured.
47+
- [Discover Rooms](/web/discover) — how ratings influence public room discovery.

0 commit comments

Comments
 (0)