Merge branch 'main' into feature/groups

docs/content/.vuepress/config.js

@@ -18,7 +18,7 @@ module.exports = {
 
   themeConfig: {
     repo: 'xSke/PluralKit',
-    docsDir: 'docs',
+    docsDir: 'docs/content/',
     docsBranch: 'main',
     editLinks: true,
     editLinkText: 'Help us improve this page!',
@@ -46,6 +46,17 @@ module.exports = {
           "/tips-and-tricks"
         ]
       },
+      {
+        title: "For server staff",
+        collapsable: false,
+        children: [
+          "/staff/permissions",
+          "/staff/moderation",
+          "/staff/disabling",
+          "/staff/logging",
+          "/staff/compatibility",
+        ]
+      },
       ["https://discord.gg/PczBt78", "Join the support server"],
     ]
   },

docs/content/api-documentation.md

@@ -519,6 +519,8 @@ The returned system and member's privacy settings will be respected, and as such
 ```
 
 ## Version history
+* 2020-07-28
+  * The unversioned API endpoints have been removed.
 * 2020-06-17 (v1.1)
   * The API now has values for granular member privacy. The new fields are as follows: `visibility`, `name_privacy`, `description_privacy`, `avatar_privacy`, `birthday_privacy`, `pronoun_privacy`, `metadata_privacy`. All are strings and accept the values of `public`, `private` and `null`.
   * The `privacy` field has now been deprecated and should not be used. It's still returned (mirroring the `visibility` field), and writing to it will write to *all privacy options*.

docs/content/command-list.md

@@ -68,7 +68,7 @@ Words in **\<angle brackets>** or **[square brackets]** mean fill-in-the-blank.
 - `pk;log channel <channel>` - Sets the given channel to log all proxied messages.
 - `pk;log disable <#channel> [#channel...]` - Disables logging messages posted in the given channel(s) (useful for staff channels and such).
 - `pk;log enable <#channel> [#channel...]` - Re-enables logging messages posted in the given channel(s).
-- `pk;logclean <on/off>` - Enables or disables [log cleanup](/guide#log-cleanup).
+- `pk;logclean <on/off>` - Enables or disables [log cleanup](./staff/compatibility.md#log-cleanup).
 - `pk;blacklist add <#channel> [#channel...]` - Adds the given channel(s) to the proxy blacklist (proxying will be disabled here)
 - `pk;blacklist remove <#channel> [#channel...]` - Removes the given channel(s) from the proxy blacklist.
 
@@ -77,16 +77,16 @@ Words in **\<angle brackets>** or **[square brackets]** mean fill-in-the-blank.
 - `pk;invite` - Sends the bot invite link for PluralKit.
 - `pk;import` - Imports a data file from PluralKit or Tupperbox.
 - `pk;export` - Exports a data file containing your system information.
-- `pk;permcheck [server id]` - [Checks the given server's permission setup](/tips#permission-checker-command) to check if it's compatible with PluralKit.
+- `pk;permcheck [server id]` - [Checks the given server's permission setup](./staff/permissions.md#permission-checker-command) to check if it's compatible with PluralKit.
 
 ## API
-*(for using the [PluralKit API](/api), useful for developers)*
+*(for using the [PluralKit API](./api-documentation.md), useful for developers)*
 - `pk;token` - DMs you a token for using the PluralKit API.
 - `pk;token refresh` - Refreshes your API token and invalidates the old one.
 
 ## Help
 - `pk;help` - Displays a basic help message describing how to use the bot.
-- `pk;help proxy` - Directs you to [this page](/guide#proxying).
+- `pk;help proxy` - Directs you to [this page](./user-guide.md#proxying).
 - `pk;system help` - Lists system-related commands.
 - `pk;member help` - Lists member-related commands.
 - `pk;switch help` - Lists switch-related commands.

docs/content/faq.md

@@ -14,3 +14,9 @@ Although this bot is designed with plural systems and their use cases in mind, t
 
 ## How can I support the bot's development?
 I (the bot author, [Ske](https://twitter.com/floofstrid)) have a Patreon. The income from there goes towards server hosting, domains, infrastructure, my Monster Energy addiction, et cetera. There are no benefits. There might never be any. But nevertheless, it can be found here: [https://www.patreon.com/floofstrid](https://www.patreon.com/floofstrid)
+
+## The name color doesn't work/can we color our proxy names?
+No. This is a limitation in Discord itself, and cannot be changed. The color command instead colors your member card that come up when you type `pk;member <member name>`.
+
+## Is it possible to block proxied messages (like blocking a user)?
+No. Since proxied messages are posted through webhooks, and those technically aren't real users on Discord's end, it's not possible to block them. Blocking PluralKit itself will also not block the webhook messages. Discord also does not allow you to control who can receive a specific message, so it's not possible to integrate a blocking system in the bot, either. Sorry :/

docs/content/index.md

@@ -1,17 +1,4 @@
 ---
-# home: true
-# heroImage: https://v1.vuepress.vuejs.org/hero.png
-# tagline: Documentation for PluralKit
-# actionText: Quick Start →
-# actionLink: /guide/
-# features:
-# - title: Feature 1 Title
-#   details: Feature 1 Description
-# - title: Feature 2 Title
-#   details: Feature 2 Description
-# - title: Feature 3 Title
-#   details: Feature 3 Description
-# footer: Made by  with ❤️
 title: Home
 ---
 

docs/content/staff/compatibility.md

@@ -0,0 +1,43 @@
+# Compatibility with other bots
+Many servers use *logger bots* for keeping track of edited and deleted messages, nickname changes, and other server events.
+Because PluralKit deletes messages as part of proxying, this can often clutter up these logs. 
+
+## Bots with PluralKit support
+Some logger bots have offical PluralKit support, and properly handle excluding proxy deletes, as well as add PK-specific information to relevant log messages:
+
+- [**Gabby Gums**](https://github.com/amadea-system/GabbyGums)
+
+If your server uses an in-house bot for logging, you can use [the API](../api-documentation.md) to implement support yourself.
+
+## Log cleanup
+Another solution is for PluralKit to automatically delete log messages from other bots when they get posted.
+PluralKit supports this through the **log cleanup** feature. To enable it, use the following command:
+
+    pk;logclean on
+    
+This requires you to have the *Manage Server* permission on the server. 
+
+### Supported bots
+At the moment, log cleanup works with the following bots:
+- [Auttaja](https://auttaja.io/) (precise)
+- [blargbot](https://blargbot.xyz/) (precise)
+- [Carl-bot](https://carl.gg/) (fuzzy)
+- [Circle](https://circlebot.xyz/) (fuzzy)
+- [Dyno](https://dyno.gg/) (precise)
+- [GearBot](https://gearbot.rocks/) (fuzzy)
+- [GenericBot](https://github.com/galenguyer/GenericBot) (precise)
+- [Logger#6088](https://logger.bot/) (precise)
+- [Logger#6278](https://loggerbot.chat/) (precise)
+- [Mantaro](https://mantaro.site/) (precise)
+- [Pancake](https://pancake.gg/) (fuzzy)
+- [SafetyAtLast](https://www.safetyatlast.net/) (fuzzy)
+- [UnbelievaBoat](https://unbelievaboat.com/) (precise)
+- Vanessa (fuzzy)
+
+::: warning
+In most cases, PluralKit will match log messages by the ID of the deleted message itself. However, some bots (marked with *(fuzzy)* above) don't include this in their logs. In this case, PluralKit will attempt to match based on other parameters, but there may be false positives. 
+
+**For best results, use a bot marked *(precise)* in the above list.**
+:::
+
+If you want support for another logging bot, [let me know on the support server](https://discord.gg/PczBt78).

docs/content/staff/disabling.md

@@ -0,0 +1,9 @@
+# Disabling proxying in a channel
+It's possible to block a channel from being used for proxying. To do so, use the `pk;blacklist` command. For example:
+
+    pk;blacklist add #admin-channel #mod-channel #welcome
+    pk;blacklist add all
+    pk;blacklist remove #general-two
+    pk;blacklist remove all
+    
+This requires you to have the *Manage Server* permission on the server. 

docs/content/staff/logging.md

@@ -0,0 +1,18 @@
+# Proxy logging
+If you want to log every proxied message to a separate channel for moderation purposes, you can use the `pk;log` command with the channel name.For example:
+
+    pk;log #proxy-log
+    
+This requires you to have the *Manage Server* permission on the server. To disable logging, use the `pk;log` command with no channel name.
+
+Log messages have the following format:
+
+![Example log message from PluralKit](../assets/log_example.png)
+
+## Blacklisting channels from logging
+Depending on your server setup, you may want to exclude some messages from logging. For example, if you have public proxy logs, you may want to exclude staff-only channels.
+
+To manage logging in a channel, use the following commands:
+
+    pk;log disable #some-secret-channel
+    pk;log enable #some-secret-channel

docs/content/staff/moderation.md

@@ -0,0 +1,34 @@
+# Moderation tools
+Since PluralKit proxies work by deleting and reposting messages through webhooks, some of Discord's standard moderation tools won't function.
+
+Specifically, you can't kick or ban individual members of a system; all moderation actions have to be taken on the concrete Discord account.
+
+## Identifying users
+You can use PluralKit's lookup tools to connect a message to the sender account. This allows you to use standard moderation tools on that account (kicking, banning, using other moderation tools, etc).
+
+### Querying messages
+To look up which account's behind a given message (as well as other information), you can either:
+
+- React to the message with the :question: emoji, which will DM you a message card
+- Use the `pk;msg <message-link>` command with the message's link, which will reply with a message card *(this also works in PluralKit's DMs)*
+
+An example of a message card is seen below:
+
+![Example of a message query card](../assets/ExampleQuery.png)
+
+### Looking up systems and accounts
+Looking up a system by its 5-character ID (`exmpl` in the above screenshot) will show you a list of its linked account IDs. For example:
+
+    pk;system exmpl
+
+You can also do the reverse operation by passing a Discord account ID (or a @mention), like so:
+
+    pk;system 466378653216014359
+
+Both commands output a system card, which includes a linked account list. These commands also work in PluralKit's DMs.
+
+### System tags
+A common rule on servers with PluralKit is to enforce system tags. System tags are a little snippet of text, a symbol, an emoji, etc, that's added to the webhook name of every message proxied by a system. A system tag will allow you to identify members that share a system at a glance. Note that this isn't enforced by the bot; this is simply a suggestion for a helpful server policy :slightly_smiling_face:
+
+## Blocking users
+It's not possible to block specific PluralKit users. Discord webhooks don't count as 'real accounts', so there's no way to block them. PluralKit also can't control who gets to see a message, so there's also no way to implement user blocking on the bot's end. Sorry. :slightly_frowning_face:

docs/content/staff/permissions.md

@@ -0,0 +1,33 @@
+# Roles and permissions
+
+PluralKit requires some channel permissions in order to function properly:
+
+- Message proxying requires the **Manage Messages** and **Manage Webhooks** permissions in a channel.
+- Most commands require the **Embed Links**, **Attach Files** and **Add Reactions** permissions to function properly.
+  - Commands with reaction menus also require **Manage Messages** to remove reactions after clicking.
+- [Proxy logging](./logging.md) requires the **Send Messages** permission in the log channel.
+- [Log cleanup](./compatibility.md#log-cleanup) requires the **Manage Messages** permission in the log channels.
+
+Denying the **Send Messages** permission will *not* stop the bot from proxying, although it will prevent it from sending command responses. Denying the **Read Messages** permission will, as any other bot, prevent the bot from interacting in that channel at all.
+
+## Webhook permissions
+Webhooks exist outside of the normal Discord permissions system, and (with a few exceptions) it's not possible to modify their permissions.
+
+However, PluralKit will make an attempt to apply the sender account's permissions to proxied messages. For example, role mentions, `@everyone`, and `@here`
+will only function if the sender account has that permission. The same applies to link embeds.
+
+For external emojis to work in proxied messages, the `@everyone` role must have the "Use External Emojis" permission. If it still doesn't work, check if the permission was denied in channel-specific permission settings.
+
+## Troubleshooting
+
+### Permission checker command
+To quickly check if PluralKit is missing channel permissions, you can use the `pk;permcheck` command in the server
+in question. It'll return a list of channels on the server with missing permissions. This may include channels
+you don't want PluralKit to have access to for one reason or another (eg. admin channels).
+
+If you want to check permissions in DMs, you'll need to add a server ID, and run the command with that.
+For example:
+
+    pk;permcheck 466707357099884544
+    
+You can find this ID [by enabling Developer Mode and right-clicking (or long-pressing) on the server icon](https://discordia.me/developer-mode).

docs/content/tips-and-tricks.md

@@ -24,16 +24,4 @@ PluralKit has a couple of useful command shorthands to reduce the typing:
 |pk;member new|pk;m n|
 |pk;switch|pk;sw|
 |pk;message|pk;msg|
-|pk;autoproxy|pk;ap|
-
-## Permission checker command
-If you're having issues with PluralKit not proxying, it may be an issue with your server's channel permission setup.
-PluralKit needs the *Read Messages*, *Manage Messages* and *Manage Webhooks* permission to function.
-
-To quickly check if PluralKit is missing channel permissions, you can use the `pk;permcheck` command in the server
-in question. It'll return a list of channels on the server with missing permissions. This may include channels
-you don't want PluralKit to have access to for one reason or another (eg. admin channels).
-
-If you want to check permissions in DMs, you'll need to add a server ID, and run the command with that.
-For example: `pk;permcheck 466707357099884544`. You can find this ID
-[by enabling Developer Mode and right-clicking (or long-pressing) on the server icon](https://discordia.me/developer-mode).
+|pk;autoproxy|pk;ap|

docs/content/user-guide.md

@@ -529,49 +529,6 @@ For example:
     pk;member Robert privacy birthday public
     pk;member Skyler privacy all private
 
-## Moderation commands
-
-### Log channel
-If you want to log every proxied message to a separate channel for moderation purposes, you can use the `pk;log` command with the channel name.
-This requires you to have the *Manage Server* permission on the server. For example:
-
-    pk;log #proxy-log
-    
-To disable logging, use the `pk;log` command with no channel name.
-
-### Channel blacklisting
-It's possible to blacklist a channel from being used for proxying. To do so, use the `pk;blacklist` command, for examplle:
-
-    pk;blacklist add #admin-channel #mod-channel #welcome
-    pk;blacklist add all
-    pk;blacklist remove #general-two
-    pk;blacklist remove all
-    
-This requires you to have the *Manage Server* permission on the server. 
-
-### Log cleanup
-Many servers use *logger bots* for keeping track of edited and deleted messages, nickname changes, and other server events. Because
-PluralKit deletes messages as part of proxying, this can often clutter up these logs. To remedy this, PluralKit can delete those
-log messages from the logger bots. To enable this, use the following command:
-
-    pk;logclean on
-    
-This requires you to have the *Manage Server* permission on the server. At the moment, log cleanup works with the following bots:
-- Auttaja 
-- blargbot
-- Carl-bot
-- Circle
-- Dyno
-- GenericBot
-- Logger (#6088 and #6278)
-- Mantaro
-- Pancake
-- UnbelievaBoat
-
-If you want support for another logging bot, [let me know on the support server](https://discord.gg/PczBt78).
-
-Another alternative is to use the **Gabby Gums** logging bot - an invite link for which can be found [on Gabby Gums' support server](https://discord.gg/Xwhk89T).
-
 ## Importing and exporting data
 If you're a user of another proxy bot (eg. Tupperbox), or you want to import a saved system backup, you can use the importing and exporting commands.